@chargebee/entitlements and @chargebee/openfeature packages

.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        node-version: [20, 22, 24]
+        node-version: [22, 24, 26]
 
     steps:
       - name: Checkout repo

AGENTS.md

@@ -0,0 +1,41 @@
+# Important information for agents
+
+- When writing something intended for human consumption, (comment, commit message, reply to prompt) use as few words as possible. Pick every word meticulously to reduce the volume to a strict minimum. Be down to the point. Less is more.
+
+- Avoid superlatives and praise. Stop telling me I am absolutely right. Give me the cold hard truth.
+
+- Avoid magic numbers and strings by extracting recurring or meaningful values into descriptive constants (const) or enums. Keep self-explanatory, one-off values inline to avoid clutter. If a value comes from a spec (e.g. HTTP 200 OK), use a constant regardless.
+
+- Reduce code indentation. Avoid Arrow Anti-Pattern. Leverage early return and continue.
+
+- Keep function names short. Less than 30 characters.
+
+- Use enums instead of booleans for function parameters.
+
+- Let the reader of the code breathe. Add empty lines between logical blocks of code.
+
+- Add a small, to the point, comment to explain *what* the block does and *why*. Use examples when possible. Propose ASCII drawings to explain complete systems.
+
+- Treat member visibility changes as a breaking design shift. Keep all fields and functions private unless external access is strictly required by the design. Prompt the user for explicit approval before changing any access modifier from private to internal or public.
+
+- Program to levels of abstraction. Lower-level mechanics (e.g., raw hardware I/O, sector parsing, direct socket streams) must be encapsulated in a dedicated driver/abstraction layer. Expose clean, high-level APIs to the rest of the application so calling code works with domain concepts, not raw implementation details.
+
+- Don't touch blocks of code unrelated to the feature you implement. e.g. Don't add comments to a block of code if you did not create it or modify it. As much as possible try to minimize the number of changed lines when implementing a feature.
+
+- Strictly adhere to the layered boundary hierarchy: each layer may only communicate with its immediate neighbor directly below it. Never "punch holes" through layers (e.g., controllers or UI components must never directly call database queries, raw hardware drivers, or low-level network clients; always route through the intermediate service/abstraction layer).
+
+- Always use {}, even on a one-line "if" statement.
+
+When you write a commit message, follow these 7 rules:
+Rule 1: Separate the subject line from the body with a single blank line.
+Rule 2: Limit the subject line to 50 characters (72 is the absolute hard limit).
+Rule 3: Capitalize the first letter of the subject line.
+Rule 4: Do not end the subject line with a period.
+Rule 5: Use the imperative mood in the subject line (e.g., "Fix bug," "Add feature,"
+        not "Fixed" or "Adds"). Test formula: It must complete the sentence: "If applied,
+        this commit will [your subject line here]".
+Rule 6: Wrap the body text manually at 72 characters to prevent Git formatting issues.
+Rule 7: Use the body to explain what and why vs. how. Assume the code explains the how;
+        the message must explain the context and reasoning.
+
+- If the prompt indicates that a bug is being fixed, don't write the fix right away. First write the test. Observe it failing. Then write the fix. And observe the test passing.

package.json

@@ -4,10 +4,10 @@
   "private": true,
   "license": "MIT",
   "engines": {
-    "node": ">=20",
-    "pnpm": ">=10"
+    "node": ">=22",
+    "pnpm": ">=11"
   },
-  "packageManager": "pnpm@10.18.1",
+  "packageManager": "pnpm@11.21.0",
   "devDependencies": {
     "@biomejs/biome": "^2.2.2",
     "@sindresorhus/tsconfig": "^7.0.0",

packages/entitlements/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+## Unreleased
+
+- A feature is declared with an ID and a mandatory, concrete default value:
+  `new Feature<number>("licensed-seats", 0)` (or `entitlements.feature(...)`,
+  which binds it to a client). `feature.get(target)` returns the typed value
+  and `feature.getDetails(target)` the full resolution. Standalone features
+  resolve against the client passed to `setDefaultEntitlements(client)`.
+  Because the default value is always concrete, its runtime type is the single
+  source for how an entitlement is parsed — there is no `type` option, no
+  inference from Chargebee's `featureType`, and no `FeatureValueType`.
+  Function-valued defaults are gone with them; await `get` and branch on the
+  result if a fallback needs to come from a database.
+- A target is `{ customerId }` or `{ subscriptionId }`. The `mode` field,
+  `ChargebeeEvaluationMode`, the `defaultMode` option, and the
+  `chargebeeCustomerId`/`chargebeeSubscriptionId`/`chargebeeEvaluationMode`
+  context keys (with `CHARGEBEE_CONTEXT_KEYS` and `getTargetFromContext`) are
+  removed. Passing both identifiers, or neither, is rejected rather than
+  resolved by precedence. Other properties on the object are ignored, so a
+  request context can be passed straight through.
+- `getValue(featureId, defaultValue, target)` is the only evaluation method on
+  both clients; `getBooleanValue`, `getStringValue`, `getNumberValue`, and
+  `getObjectValue` are removed, as are the standalone
+  `resolveBooleanEntitlement`/`resolveString...`/`resolveNumber...`/`resolveObject...`
+  helpers.
+- `logger` moved from every method signature to `ChargebeeEntitlementsOptions`.
+- Snapshots no longer carry `targetMode`; `createEntitlementsSnapshot` takes
+  `(entitlements, ttlMs, now?)` and now lives on `/server`, alongside the
+  `writeSnapshot` call that consumes it. `serializeEntitlementsSnapshot` and
+  `parseSerializedEntitlementsSnapshot` moved to `/cache`, next to the
+  `EntitlementsStorage` interface that needs them.
+- Trimmed the export surface substantially. The root entry point is now
+  `Feature`, `setDefaultEntitlements`, and the five types that appear in their
+  signatures; `Feature` has exactly one import path instead of being
+  re-exported from `/server` as well. Removed `defineFeatures`,
+  `getDefaultEntitlements`, `toResolutionDetails` (now internal to
+  `@chargebee/openfeature`), the `advanced.resolveTarget` option, and the
+  `FeatureOptions`, `FeatureGetOptions`, `FeatureDefaultValue`,
+  `FeatureDefaultResolver`, `FeatureDefaultContext`, `FeatureDefinition`,
+  `FeatureCatalog`, `FeatureTarget`, `EntitlementsEvaluator`,
+  `EvaluationContextLike`, `RefreshOnMiss`, `SnapshotOperation`,
+  `EntitlementsSnapshotResult`, `EntitlementsRelayHandler`,
+  `EntitlementsRelaySource`, and `ChargebeeEntitlementsClient` types.
+- Replaced `zod` dependency in snapshot parsing with zero-dependency lightweight validation.
+- Deduplicated internal evaluation, storage, and loader normalization logic.
+- Initial extraction of the framework-agnostic Chargebee entitlements client
+  from `@chargebee/openfeature`. `ChargebeeEntitlements` (server) and
+  `ChargebeeEntitlementsWebClient` (web) can now be used directly, without an
+  OpenFeature SDK. `@chargebee/openfeature` is now a thin adapter over this
+  package.
+- The shared snapshot/cache/relay modules (`shared`, `cache`, `server`,
+  `web`, `nextjs`) moved here unchanged from `@chargebee/openfeature`. See
+  that package's changelog for their history prior to the split.
+- The default cache-key namespace changed from `chargebee:openfeature:v1` to
+  `chargebee:entitlements:v1`. Pass `cacheNamespace` explicitly if you need to
+  keep reading previously cached keys.

packages/entitlements/LICENSE.md

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+Copyright (c) 2025 - present, Chargebee
+
+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.