@toggld/js 0.0.0-stage → 0.9.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,356 @@
-# Temporary Holding Version
+# @toggld/js
 
-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.
+The Toggld SDK for server-side JavaScript. Evaluate feature flags from Node.js
+servers, and from serverless and edge runtimes (Cloudflare Workers, Vercel,
+AWS Lambda), against the Toggld flag API.
+
+> **Renamed from `@toggld/node`.** Up to 0.8.0 this package was published as
+> `@toggld/node`. Replace the package name in your imports and
+> `package.json`. The modes were renamed too: `mode: "local"` is now
+> `mode: "sync"` (the default), and `sync: { file }` is now
+> `mode: "file", file`. Both old forms throw a `TypeError`. `@toggld/node`
+> gets no more releases.
+
+Four entries ship from one implementation:
+
+- **`@toggld/js`** — a plain Promise API with **no runtime dependencies**.
+- **`@toggld/js/effect`** — the native [Effect](https://effect.website) API:
+  the client as a service + `Layer`. Only this entry needs `effect`.
+- **`@toggld/js/serverless`** — the remote client for serverless and edge
+  runtimes: one bulk evaluation request per incoming request, with an optional
+  cache. No `node:` imports, so it runs on Workers without `nodejs_compat`.
+  See [Serverless client](#serverless-client).
+- **`@toggld/js/serverless/effect`** — the serverless client as the same
+  Effect `ToggldClient` service as `@toggld/js/effect`.
+
+Three evaluation modes for `ToggldClient` (`mode`), plus the serverless client:
+
+- **Sync** (`mode: "sync"`, the default) — a copy of the flag rules stays
+  current in the background (a snapshot fetch plus a live WebSocket stream,
+  with polling as a safety net and fallback) and every evaluation runs
+  **in your process** on the bundled engine, with no request per evaluation.
+  See [ADR-0012](../../docs/adr/0012-definition-sync-and-local-evaluation.md).
+- **File** (`mode: "file"`) — the same in-process evaluation, from a flag
+  **file** on disk, watched for edits. No network. See
+  [Flag files](#flag-files-offline) below.
+- **Remote** (`mode: "remote"`) — every call asks the flag API, which evaluates
+  the flag against your context and returns the resolved value (OpenFeature
+  "remote evaluation" over the OFREP endpoints).
+- **Serverless** (`@toggld/js/serverless`) — one remote bulk request per
+  incoming request, for serverless and edge runtimes. See
+  [Serverless client](#serverless-client).
+
+### Why sync is the default
+
+- **Fast.** An evaluation takes microseconds, not a network round trip.
+- **Keeps working.** After the first sync, evaluations use the last snapshot
+  while the API is unreachable.
+- **No request per lookup.** Sync-mode evaluations never reach the API, so they
+  are not billable evaluation requests and do not use your rate limit.
+  Remote mode sends one request for each evaluation.
+
+### What sync mode needs
+
+- **A secret SDK key** (`ffk_…`): a server SDK key or a management key. The
+  snapshot holds your targeting rules, so public browser tokens (`ffp_…`)
+  cannot download it. Creating a sync-mode client with a public token, without
+  a key, or without a valid `endpoint` throws a `TypeError` at once.
+- **Network access to `/sync/v1`** on the API: `GET /sync/v1/flags` over
+  HTTPS, and the `/sync/v1/stream` WebSocket. Without a usable WebSocket, the
+  SDK keeps polling the snapshot (every 30 s by default) and retries the stream.
+- **A long-lived process**, such as a web server or a worker. The sync runs
+  in the background for the life of the client.
+
+### When to use remote mode
+
+Pass `mode: "remote"` when the process must not hold your targeting rules, or
+keeps no memory between requests:
+
+- **A public token** (`ffp_…`), or any process that should see evaluated values
+  only, not the rules.
+- **Runtimes without memory between requests**, such as Fastly Compute.
+
+On **serverless functions** (AWS Lambda, Vercel and Netlify functions) and
+**edge runtimes** (Cloudflare Workers, Vercel Edge), use the
+[serverless client](#serverless-client) instead: it sends one bulk request per
+incoming request, which is one billable request however many flags you read.
+In sync mode, `create` throws a
+`TypeError` on Workers and Vercel Edge, and logs one warning on AWS Lambda
+(the process freezes between invocations, so the stream and poll stall).
+
+```ts
+const client = await ToggldClient.create({ sdkKey, endpoint, mode: "remote" })
+```
+
+Short scripts and CLI tools can use any mode. In sync mode, `create` waits
+for the snapshot, and the script must call `close()` to exit.
+
+## Install
+
+```bash
+pnpm add @toggld/js
+```
+
+That is all the Promise API needs. For the Effect API, install `effect` too
+(`pnpm add effect`): it is an optional peer dependency (`^4.0.5`), so
+`@toggld/js/effect` runs on your app's copy of Effect, and its `Layer`
+composes with the app's layers. Importing `@toggld/js/effect` without
+`effect` installed fails with `ERR_MODULE_NOT_FOUND`.
+
+## Promise API
+
+```ts
+import { ToggldClient } from "@toggld/js"
+
+// Sync mode (the default). `create` resolves once the first snapshot
+// has synced, or after `sync.readyTimeoutMs` (5 s).
+const client = await ToggldClient.create({
+  sdkKey: process.env.TOGGLD_SDK_KEY!, // a secret SDK key (ffk_…)
+  endpoint: "https://api.toggld.io",
+})
+
+// Typed getters — return the default on any error, never throw.
+const on = await client.getBooleanValue("new-checkout", false, {
+  targetingKey: "user-123",
+  plan: "premium",
+})
+
+// Full OpenFeature evaluation details.
+const details = await client.getStringDetails("theme", "light", { targetingKey: "user-123" })
+//    ^ { flagKey, value, variant, reason, errorCode, errorMessage, flagMetadata }
+
+// Every flag for the environment, evaluated in-process.
+const everything = await client.evaluateAll({ targetingKey: "user-123" })
+
+await client.close() // stops background sync and sends remaining telemetry
+```
+
+Getters exist for each flag type: `getBooleanValue` / `getBooleanDetails`,
+`getStringValue` / `…`, `getNumberValue` / `…`, and `getObjectValue<T>` / `…`.
+
+## Effect API
+
+```ts
+import { Effect } from "effect"
+import { ToggldClient, layer } from "@toggld/js/effect"
+
+const program = Effect.gen(function* () {
+  const flags = yield* ToggldClient
+  return yield* flags.getBooleanValue("new-checkout", false, { targetingKey: "user-123" })
+})
+
+program.pipe(
+  Effect.provide(layer({ sdkKey, endpoint })),
+  Effect.runPromise,
+)
+```
+
+The `layer` is self-contained, so you only provide this one layer. It is a thin
+wrapper over the same client the Promise API uses: like `create`, building it
+waits for the first snapshot for up to `sync.readyTimeoutMs`. The layer's scope
+owns the client, and closing the scope closes it (sync stops, the stream
+closes, and remaining telemetry is sent). Build the layer once per process, for
+example with a `ManagedRuntime`, not once per request. Sync- and file-mode
+evaluations are synchronous effects; remote ones are interruptible, and interrupting one aborts
+its request.
+
+## Serverless client
+
+`@toggld/js/serverless` is a remote client for runtimes that run code only
+while they handle a request. Create the client once per isolate or process;
+create a request view per incoming request with `forRequest(ctx)`.
+
+```ts
+import { createServerlessClient, type ServerlessClient } from "@toggld/js/serverless"
+
+let flags: ServerlessClient | undefined
+
+export default {
+  async fetch(request: Request, env: Env, ctx: ExecutionContext) {
+    flags ??= createServerlessClient({ sdkKey: env.TOGGLD_SDK_KEY, endpoint: "https://api.toggld.io" })
+    const f = flags.forRequest(ctx)
+    const on = await f.getBooleanValue("new-checkout", false, { targetingKey: "user-123" })
+    return new Response(on ? "new" : "old")
+  },
+}
+```
+
+The first evaluation in a view sends one bulk request
+(`POST /ofrep/v1/evaluate/flags`) with its context. Every later read in that
+view with the same context uses the answer; a different context sends its own
+request. Nothing is kept between requests, so a change shows on the next
+request. A bulk request is one billable request, whatever the number of flags.
+Failures (network, timeout after `timeoutMs`, default 1.5 s, or a refusal)
+resolve to your defaults with an error code; nothing throws.
+
+To send fewer requests, pass a `cache`: `memoryCache({ ttlMs })` keeps results
+in isolate memory, and any key-value store can implement `EvaluationCache`. A
+cache trades freshness for fewer billable requests. On AWS Lambda and Node.js
+serverless functions, call `flags.forRequest()` without a context; cache
+writes then run inline.
+
+The client counts each read that resolves a flag (the API does not count bulk
+requests in analytics) and sends the counts to `POST /v1/telemetry` when the
+oldest is 30 seconds old or 1,000 groups have built up: in the request's
+`waitUntil`, or started without waiting when there is none. Evaluations never
+wait for it. Set `telemetry: false` to send nothing. See the
+[serverless client guide](https://docs.toggld.io/sdks/js/serverless) and
+[ADR-0020](../../docs/adr/0020-serverless-client-and-toggld-js.md).
+
+## Options
+
+| Option           | Type                  | Default          | Notes                                                            |
+| ---------------- | --------------------- | ---------------- | ---------------------------------------------------------------- |
+| `sdkKey`         | `string`              | —                | Secret evaluation (or management) key, `ffk_…`; sent as `Bearer`. A public token (`ffp_…`) needs `mode: "remote"`. |
+| `endpoint`       | `string`              | —                | Base URL of the flag API. It may have a path prefix, for a [proxy on your own domain](https://docs.toggld.io/sdks/proxy). |
+| `mode`           | `"sync" \| "file" \| "remote"` | `"sync"` | Sync = background sync + in-process engine. File = in-process engine over a flag file. Remote = one OFREP request per evaluation. |
+| `file`           | `string`              | `./toggld.flags.json` | The flag file, in file mode only (a `TypeError` with any other mode). `TOGGLD_FLAGS_FILE` overrides it. |
+| `sync.transport` | `"ws" \| "poll"`      | `"ws"`           | Sync mode: live stream (with poll safety net) vs polling only.   |
+| `sync.pollIntervalMs` | `number`         | `30000`          | Sync mode: snapshot poll cadence; cold start retries faster. Does not apply to files. |
+| `sync.readyTimeoutMs` | `number`         | `5000`           | Sync mode: how long `create` (and the Effect `layer`) waits for the first snapshot. |
+| `defaultContext` | `EvaluationContext`   | `{}`             | Merged under per-call context (per-call attributes win).         |
+| `timeoutMs`      | `number`              | `5000`           | Per-request timeout.                                             |
+| `fetch`          | `typeof fetch`        | `globalThis.fetch` | Custom fetch (tests, proxies, instrumentation).               |
+
+### Readiness
+
+In sync mode, `create` waits for the first snapshot or `sync.readyTimeoutMs`
+(default 5 s), whichever comes first. If the snapshot has not arrived by then,
+the SDK logs one warning with the last sync error (for example HTTP 401 for a
+wrong key), and sync keeps retrying in the background. Until a snapshot
+arrives, evaluations return your defaults with `reason: "ERROR"` and
+`errorCode: "PROVIDER_NOT_READY"`, and their `errorMessage` names the last sync
+error. `evaluateAll` returns an empty array. `client.ready()` waits for the
+first snapshot with no time limit, so add your own timeout if you use it at
+startup. In file mode, `create` resolves after the first read of the file. In
+remote mode, `create` and `ready()` resolve at once.
+
+### Shutdown
+
+Call `close()` when the process stops. It stops the sync, closes the stream,
+and sends the remaining telemetry (bounded by `timeoutMs`). A sync-mode client keeps
+the Node.js process alive until you close it, so a short script must call
+`close()` to exit.
+
+Changes on the connected Node instance normally arrive through WebSocket pushes.
+The SDK also polls every 30 seconds, even while the stream stays healthy.
+Polling recovers writes from other instances and announcements that the bounded
+server buffer drops. With healthy requests, the conservative bound is
+`sync.pollIntervalMs + 2 * timeoutMs`, plus scheduling delays, or 40 seconds by default.
+The [Node sync guide](../../docs/node-sync.md) defines the assumptions and deployment requirements.
+
+### How fast is sync mode?
+
+`pnpm bench:sync` (from the repo root) runs the same workload with sync off vs
+on — representative numbers on a laptop, loopback server:
+
+```
+sync OFF (remote OFREP)        ~11,600 evals/s   p50 2.4 ms
+sync ON  (local engine)     ~1,090,000 evals/s   p50 27 µs   (0.6 µs single-caller)
+```
+
+## Flag files (offline)
+
+For local development, CI, or offline runs, a client in file mode evaluates
+against a **file** instead of syncing over the network — same engine, same results, no
+flag API required. Generate the file with the bundled CLI:
+
+```bash
+# Fetch the environment's current flags into ./toggld.flags.json.
+# Prompts for the key if you omit --sdk-key (or set TOGGLD_SDK_KEY).
+# Uses https://api.toggld.io unless you pass --api or set TOGGLD_API_URL.
+npx @toggld/js pull --sdk-key ffk_…
+```
+
+Then create a client in file mode — no `sdkKey` or `endpoint` needed:
+
+```ts
+const client = await ToggldClient.create({
+  mode: "file",
+  file: "./toggld.flags.json", // the default; omit it to use this path
+})
+```
+
+The file is a `FlagSnapshot` (the exact wire snapshot the SDK syncs) wrapped in a
+small provenance envelope, so it is human-readable, diffable, and editable —
+flip an `enabled`, nudge a rollout, commit a fixture. **Edits are picked up
+live** (the file is watched); no restart, and no need to change `version`.
+The client also re-reads the file every 30 seconds as a safety net
+(`sync.pollIntervalMs` does not apply to files).
+
+You can also redirect *any* client to a file with **no code change** by setting
+`TOGGLD_FLAGS_FILE` — it switches a client in any mode to file mode with that
+path, even a client with `mode: "remote"`, and overrides `file`:
+
+```bash
+TOGGLD_FLAGS_FILE=./toggld.flags.json node server.js
+```
+
+`pull` needs a secret key (`ffk_…`); it is one-shot and idempotent (an unchanged
+version is not rewritten — pass `--force` to override). See
+[ADR-0013](../../docs/adr/0013-local-flag-files-and-pull-cli.md). Remote-segment
+membership (ADR-0006) is not yet available offline; a file-mode client warns
+once and treats a remote segment's non-rule-matched subjects as non-members.
+
+## Error semantics
+
+Evaluation never throws. On a network failure, timeout, unknown flag, server
+error, or a value whose type doesn't match the requested getter, the call
+resolves to your **default value**. The `*Details` methods carry `reason:
+"ERROR"` and an OpenFeature `errorCode` (`FLAG_NOT_FOUND`, `TYPE_MISMATCH`,
+`TARGETING_KEY_MISSING`, `PARSE_ERROR`, `GENERAL`, …) describing what happened.
+A rejected request, such as HTTP 401 for a wrong SDK key or HTTP 429 for a rate
+limit, reports `GENERAL` with the HTTP status in `errorMessage`.
+
+
+## Evaluation telemetry
+
+The SDK counts the flags your code reads for analytics (the API does not count
+bulk requests). Sync mode counts every evaluation; remote mode counts each flag
+`evaluateAll` returns (the API counts its single evaluations); the serverless
+client counts each read that resolves a flag, and sends from requests (see
+[Serverless client](#serverless-client)).
+It groups counts by flag, variant, result reason, and UTC minute. The SDK sends
+batches to `POST /v1/telemetry` every 30 seconds and during `close()`.
+Evaluation calls do not wait for these requests. Both SDK APIs use this reporter.
+
+The SDK reports engine results for known flags, including engine errors.
+It excludes unknown flags, calls before readiness, and errors from typed getters.
+Each bulk evaluation counts each flag once. The SDK sends no user identities,
+evaluation context, values, or metadata. File mode sends no telemetry, even
+when credentials are present.
+
+```ts
+const client = await ToggldClient.create({
+  endpoint,
+  sdkKey,
+  telemetry: { flushIntervalMs: 30_000 },
+})
+
+await client.getBooleanValue("checkout", false, { targetingKey: "user-123" })
+await client.flushTelemetry()
+await client.close()
+```
+
+Set `telemetry: false` to disable reporting. Use `flushTelemetry()` to send counts
+before the next interval. Effect users can yield `client.flushTelemetry` and close
+the layer scope to flush remaining counts. A flush failure leaves the batch
+queued for the next attempt. Retries keep the same batch ID to prevent duplicate
+counts after a lost response.
+
+The SDK holds at most 10,000 active groups and 10,000 groups awaiting retry.
+If the active buffer fills, the SDK drops new groups. Each request contains at
+most 1,000 groups. Each count stops at 1,000,000,000. Keys and variants longer
+than 256 characters do not produce telemetry. Process crashes can lose buffered
+counts. Closing the client limits its final telemetry attempt to `timeoutMs`,
+which defaults to five seconds. Counts remain approximate.
+
+
+The integration suite can use Postgres for the complete SDK-to-storage path.
+It creates tenants and flags, so use a disposable database. From the repository
+root, set `DATABASE_URL` to that database and run the command below. The test
+server applies migrations before it starts.
+
+```bash
+TOGGLD_TEST_POSTGRES=1 DATABASE_URL=postgres://postgres:postgres@localhost:55439/toggld pnpm --filter @toggld/js exec vitest run test/telemetry.test.ts
+```

package/dist/cli.d.mts

@@ -0,0 +1 @@
+export {}