@spotify-confidence/openfeature-server-provider-local 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## [0.3.0](https://github.com/spotify/confidence-resolver/compare/openfeature-provider-js-v0.2.0...openfeature-provider-js-v0.3.0) (2025-12-02)
+
+
+### ⚠ BREAKING CHANGES
+
+* migrate to cdn state fetch, publish logs using client secret ([#166](https://github.com/spotify/confidence-resolver/issues/166))
+
+### Features
+
+* migrate to cdn state fetch, publish logs using client secret ([#166](https://github.com/spotify/confidence-resolver/issues/166)) ([6c8d959](https://github.com/spotify/confidence-resolver/commit/6c8d959f124faa419c1ace103d8832457248eb26))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * rust-guest bumped from 0.1.10 to 0.1.11
+
 ## [0.2.0](https://github.com/spotify/confidence-resolver/compare/openfeature-provider-js-v0.1.1...openfeature-provider-js-v0.2.0) (2025-11-24)
 
 

package/README.md

@@ -1,4 +1,4 @@
-# @spotify-confidence/openfeature-server-provider-local
+# Confidence OpenFeature Local Provider for JavaScript
 
 OpenFeature provider for the Spotify Confidence resolver (local mode, powered by WebAssembly). It periodically fetches resolver state, evaluates flags locally, and flushes evaluation logs to the Confidence backend.
 
@@ -29,6 +29,18 @@ Notes:
 
 ---
 
+## Getting Your Credentials
+
+You'll need a **client secret** from Confidence to use this provider.
+
+**📖 See the [Integration Guide: Getting Your Credentials](../INTEGRATION_GUIDE.md#getting-your-credentials)** for step-by-step instructions on:
+- How to navigate the Confidence dashboard
+- Creating a Backend integration
+- Creating a test flag for verification
+- Best practices for credential storage
+
+---
+
 ## Quick start (Node)
 
 ```ts
@@ -37,8 +49,6 @@ import { createConfidenceServerProvider } from '@spotify-confidence/openfeature-
 
 const provider = createConfidenceServerProvider({
   flagClientSecret: process.env.CONFIDENCE_FLAG_CLIENT_SECRET!,
-  apiClientId: process.env.CONFIDENCE_API_CLIENT_ID!,
-  apiClientSecret: process.env.CONFIDENCE_API_CLIENT_SECRET!,
   // initializeTimeout?: number
   // flushInterval?: number
   // fetch?: typeof fetch (Node <18 or custom transport)
@@ -49,13 +59,20 @@ await OpenFeature.setProviderAndWait(provider);
 
 const client = OpenFeature.getClient();
 
+// Create evaluation context with user attributes for targeting
+const context = {
+  targetingKey: 'user-123',
+  country: 'US',
+  plan: 'premium',
+};
+
 // Evaluate a boolean flag
-const details = await client.getBooleanDetails('my-flag', false, { targetingKey: 'user-123' });
-console.log(details.value, details.reason);
+const enabled = await client.getBooleanValue('test-flag.enabled', false, context);
+console.log('Flag value:', enabled);
 
 // Evaluate a nested value from an object flag using dot-path
 // e.g. flag key "experiments" with payload { groupA: { ratio: 0.5 } }
-const ratio = await client.getNumberValue('experiments.groupA.ratio', 0, { targetingKey: 'user-123' });
+const ratio = await client.getNumberValue('experiments.groupA.ratio', 0, context);
 
 // On shutdown, flush any pending logs
 await provider.onClose();
@@ -63,61 +80,73 @@ await provider.onClose();
 
 ---
 
-## Options
+## Evaluation Context
 
-- `flagClientSecret` (string, required): The flag client secret used during evaluation.
-- `apiClientId` (string, required): OAuth client ID for Confidence IAM.
-- `apiClientSecret` (string, required): OAuth client secret for Confidence IAM.
-- `initializeTimeout` (number, optional): Max ms to wait for initial state fetch. Defaults to 30_000.
-- `flushInterval` (number, optional): Interval in ms for sending evaluation logs. Defaults to 10_000.
-- `fetch` (optional): Custom `fetch` implementation. Required for Node < 18; for Node 18+ you can omit.
+The evaluation context contains information about the user/session being evaluated for targeting and A/B testing.
 
-The provider periodically:
-- Refreshes resolver state (default every 30s)
-- Flushes flag evaluation logs to the backend
+### TypeScript/JavaScript Examples
+
+```typescript
+// Simple attributes
+const context = {
+  targetingKey: 'user-123',
+  country: 'US',
+  plan: 'premium',
+  age: 25,
+};
+```
 
 ---
 
-## Migration from online resolver
-If you're currently using the ["online resolver"](https://github.com/spotify/confidence-sdk-js/tree/main/packages/openfeature-server-provider) and wants to improve the resolve latency, [migration](MIGRATION.md) is easy!
+## Error Handling
 
----
+The provider uses a **default value fallback** pattern - when evaluation fails, it returns your specified default value instead of throwing an error.
 
-## Sticky Assignments
+**📖 See the [Integration Guide: Error Handling](../INTEGRATION_GUIDE.md#error-handling)** for:
+- Common failure scenarios
+- Error codes and meanings
+- Production best practices
+- Monitoring recommendations
 
-Confidence supports "sticky" flag assignments to ensure users receive consistent variant assignments even when their context changes or flag configurations are updated. This SDK falls back to a cloud resolve in these cases.
+### TypeScript/JavaScript Examples
 
-> **ℹ️ Latency Considerations**
->
-> When a sticky assignment is needed, the provider makes a **network call to Confidence's cloud resolvers**. This introduces additional latency (typically 50-200ms depending on your location) compared to local WASM evaluation.
->
-> **Coming soon**: We're developing support for custom materialization storage (Redis, database, etc.) that will eliminate this network call and keep evaluation latency consistently low.
+```typescript
+// The provider returns the default value on errors
+const enabled = await client.getBooleanValue('my-flag.enabled', false, context);
+// enabled will be 'false' if evaluation failed
 
-### How it works
+// For detailed error information, use getBooleanDetails()
+const details = await client.getBooleanDetails('my-flag.enabled', false, context);
+if (details.errorCode) {
+    console.error('Flag evaluation error:', details.errorMessage);
+    console.log('Reason:', details.reason);
+}
+```
 
-When a flag is evaluated for a user, Confidence creates a "materialization" - a snapshot of which variant that user was assigned. On subsequent evaluations, the same variant is returned even if:
-- The user's context attributes change (e.g., different country, device type)
-- The flag's targeting rules are modified
-- New assignments are paused
+---
 
-### Implementation
+## Options
 
-The provider uses a **remote resolver fallback** for sticky assignments:
-- First, the local WASM resolver attempts to resolve the flag
-- If sticky assignment data is needed, the provider makes a network call to Confidence's cloud resolvers
-- Materializations are stored on Confidence servers with a **90-day TTL** (automatically renewed on access)
-- No local storage or database setup required
+- `flagClientSecret` (string, required): The flag client secret used during evaluation and authentication.
+- `initializeTimeout` (number, optional): Max ms to wait for initial state fetch. Defaults to 30_000.
+- `flushInterval` (number, optional): Interval in ms for sending evaluation logs. Defaults to 10_000.
+- `fetch` (optional): Custom `fetch` implementation. Required for Node < 18; for Node 18+ you can omit.
 
-### Benefits
+The provider periodically:
+- Refreshes resolver state (default every 30s)
+- Flushes flag evaluation logs to the backend
 
-- **Zero configuration**: Works out of the box with no additional setup
-- **Managed storage**: Confidence handles all storage, TTL, and consistency
-- **Automatic renewal**: TTL is refreshed on each access
-- **Global availability**: Materializations are available across all your services
+---
 
-### Coming Soon: Custom Materialization Storage
+## Sticky Assignments
+
+The provider supports **Sticky Assignments** for consistent variant assignments across flag evaluations.
 
-We're working on support for connecting your own materialization storage repository (Redis, database, file system, etc.) to eliminate network calls for sticky assignments and have full control over storage. This feature is currently in development.
+**📖 See the [Integration Guide: Sticky Assignments](../INTEGRATION_GUIDE.md#sticky-assignments)** for:
+- How sticky assignments work
+- Server-managed storage (zero configuration)
+- Latency considerations
+- Custom storage options (currently Java-only, coming soon to JavaScript)
 
 ---
 
@@ -129,13 +158,19 @@ Namespaces:
 - Core: `cnfd:*`
 - Fetch/middleware: `cnfd:fetch:*` (e.g. retries, auth renewals, request summaries)
 
+Log levels are hierarchical:
+- `cnfd:debug` enables debug, info, warn, and error
+- `cnfd:info` enables info, warn, and error
+- `cnfd:warn` enables warn and error
+- `cnfd:error` enables error only
+
 Enable logs:
 
 - Node:
 ```bash
 DEBUG=cnfd:* node app.js
 # or narrower
-DEBUG=cnfd:info,cnfd:error,cnfd:fetch:* node app.js
+DEBUG=cnfd:info,cnfd:fetch:* node app.js
 ```
 
 - Browser (in DevTools console):
@@ -171,19 +206,6 @@ The package exports a browser ESM build that compiles the WASM via streaming and
 
 ---
 
-## Troubleshooting
-
-- Provider stuck in NOT_READY/ERROR:
-  - Verify `apiClientId`/`apiClientSecret` and `flagClientSecret` are correct.
-  - Ensure outbound access to Confidence endpoints and GCS.
-  - Enable `DEBUG=cnfd:*` for more detail.
-
-- No logs appear:
-  - Install `debug` and enable the appropriate namespaces.
-  - Check that your environment variable/`localStorage.debug` is set before your app initializes the provider.
-
----
-
 ## License
 
 See the root `LICENSE`.

package/dist/index.browser.d.ts

@@ -1,7 +1,8 @@
 import { BinaryReader, BinaryWriter } from "@bufbuild/protobuf/wire";
 import { EvaluationContext, JsonValue, Provider, ProviderMetadata, ProviderStatus, ResolutionDetails } from "@openfeature/server-sdk";
 
-//#region src/proto/api.d.ts
+//#region src/proto/confidence/flags/resolver/v1/types.d.ts
+
 declare enum SdkId {
   SDK_ID_UNSPECIFIED = 0,
   SDK_ID_JAVA_PROVIDER = 1,
@@ -28,6 +29,33 @@ declare enum SdkId {
   SDK_ID_JS_LOCAL_SERVER_PROVIDER = 22,
   UNRECOGNIZED = -1,
 }
+/**
+* (-- api-linter: core::0123::resource-annotation=disabled
+*     aip.dev/not-precedent: SDKs are not internal Confidence resources. --)
+*/
+interface Sdk {
+  /** Name of a Confidence SDKs. */
+  id?: SdkId | undefined;
+  /** Custom name for non-Confidence SDKs. */
+  customId?: string | undefined;
+  /** Version of the SDK. */
+  version: string;
+}
+declare const Sdk: MessageFns$2<Sdk>;
+type Builtin$2 = Date | Function | Uint8Array | string | number | boolean | undefined;
+type DeepPartial$2<T> = T extends Builtin$2 ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial$2<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial$2<U>> : T extends {} ? { [K in keyof T]?: DeepPartial$2<T[K]> } : Partial<T>;
+type KeysOfUnion$2<T> = T extends T ? keyof T : never;
+type Exact$2<P, I extends P> = P extends Builtin$2 ? P : P & { [K in keyof P]: Exact$2<P[K], I[K]> } & { [K in Exclude<keyof I, KeysOfUnion$2<P>>]: never };
+interface MessageFns$2<T> {
+  encode(message: T, writer?: BinaryWriter): BinaryWriter;
+  decode(input: BinaryReader | Uint8Array, length?: number): T;
+  fromJSON(object: any): T;
+  toJSON(message: T): unknown;
+  create<I extends Exact$2<DeepPartial$2<T>, I>>(base?: I): T;
+  fromPartial<I extends Exact$2<DeepPartial$2<T>, I>>(object: I): T;
+}
+//#endregion
+//#region src/proto/types.d.ts
 declare enum ResolveReason {
   /** RESOLVE_REASON_UNSPECIFIED - Unspecified enum. */
   RESOLVE_REASON_UNSPECIFIED = 0,
@@ -50,11 +78,8 @@ declare enum ResolveReason {
   RESOLVE_REASON_ERROR = 6,
   UNRECOGNIZED = -1,
 }
-interface Sdk {
-  id?: SdkId | undefined;
-  customId?: string | undefined;
-  version: string;
-}
+//#endregion
+//#region src/proto/resolver/api.d.ts
 interface ResolveFlagsRequest {
   /**
   * If non-empty, the specific flags are resolved, otherwise all flags
@@ -113,10 +138,6 @@ interface ResolvedFlag {
   /** The reason to why the flag could be resolved or not. */
   reason: ResolveReason;
 }
-interface SetResolverStateRequest {
-  state: Uint8Array;
-  accountId: string;
-}
 /** Request for resolving flags with sticky (materialized) assignments */
 interface ResolveWithStickyRequest {
   /** The standard resolve request */
@@ -176,19 +197,36 @@ interface ResolveWithStickyResponse_MaterializationUpdate {
   rule: string;
   variant: string;
 }
-declare const Sdk: MessageFns<Sdk>;
-declare const ResolveFlagsRequest: MessageFns<ResolveFlagsRequest>;
-declare const ResolveFlagsResponse: MessageFns<ResolveFlagsResponse>;
-declare const ResolvedFlag: MessageFns<ResolvedFlag>;
+declare const ResolveFlagsRequest: MessageFns$1<ResolveFlagsRequest>;
+declare const ResolveFlagsResponse: MessageFns$1<ResolveFlagsResponse>;
+declare const ResolvedFlag: MessageFns$1<ResolvedFlag>;
+declare const ResolveWithStickyRequest: MessageFns$1<ResolveWithStickyRequest>;
+declare const MaterializationMap: MessageFns$1<MaterializationMap>;
+declare const MaterializationInfo: MessageFns$1<MaterializationInfo>;
+declare const ResolveWithStickyResponse: MessageFns$1<ResolveWithStickyResponse>;
+declare const ResolveWithStickyResponse_Success: MessageFns$1<ResolveWithStickyResponse_Success>;
+declare const ResolveWithStickyResponse_MissingMaterializations: MessageFns$1<ResolveWithStickyResponse_MissingMaterializations>;
+declare const ResolveWithStickyResponse_MissingMaterializationItem: MessageFns$1<ResolveWithStickyResponse_MissingMaterializationItem>;
+declare const ResolveWithStickyResponse_MaterializationUpdate: MessageFns$1<ResolveWithStickyResponse_MaterializationUpdate>;
+type Builtin$1 = Date | Function | Uint8Array | string | number | boolean | undefined;
+type DeepPartial$1<T> = T extends Builtin$1 ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial$1<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial$1<U>> : T extends {} ? { [K in keyof T]?: DeepPartial$1<T[K]> } : Partial<T>;
+type KeysOfUnion$1<T> = T extends T ? keyof T : never;
+type Exact$1<P, I extends P> = P extends Builtin$1 ? P : P & { [K in keyof P]: Exact$1<P[K], I[K]> } & { [K in Exclude<keyof I, KeysOfUnion$1<P>>]: never };
+interface MessageFns$1<T> {
+  encode(message: T, writer?: BinaryWriter): BinaryWriter;
+  decode(input: BinaryReader | Uint8Array, length?: number): T;
+  fromJSON(object: any): T;
+  toJSON(message: T): unknown;
+  create<I extends Exact$1<DeepPartial$1<T>, I>>(base?: I): T;
+  fromPartial<I extends Exact$1<DeepPartial$1<T>, I>>(object: I): T;
+}
+//#endregion
+//#region src/proto/messages.d.ts
+interface SetResolverStateRequest {
+  state: Uint8Array;
+  accountId: string;
+}
 declare const SetResolverStateRequest: MessageFns<SetResolverStateRequest>;
-declare const ResolveWithStickyRequest: MessageFns<ResolveWithStickyRequest>;
-declare const MaterializationMap: MessageFns<MaterializationMap>;
-declare const MaterializationInfo: MessageFns<MaterializationInfo>;
-declare const ResolveWithStickyResponse: MessageFns<ResolveWithStickyResponse>;
-declare const ResolveWithStickyResponse_Success: MessageFns<ResolveWithStickyResponse_Success>;
-declare const ResolveWithStickyResponse_MissingMaterializations: MessageFns<ResolveWithStickyResponse_MissingMaterializations>;
-declare const ResolveWithStickyResponse_MissingMaterializationItem: MessageFns<ResolveWithStickyResponse_MissingMaterializationItem>;
-declare const ResolveWithStickyResponse_MaterializationUpdate: MessageFns<ResolveWithStickyResponse_MaterializationUpdate>;
 type Builtin = Date | Function | Uint8Array | string | number | boolean | undefined;
 type DeepPartial<T> = T extends Builtin ? T : T extends globalThis.Array<infer U> ? globalThis.Array<DeepPartial<U>> : T extends ReadonlyArray<infer U> ? ReadonlyArray<DeepPartial<U>> : T extends {} ? { [K in keyof T]?: DeepPartial<T[K]> } : Partial<T>;
 type KeysOfUnion<T> = T extends T ? keyof T : never;
@@ -212,8 +250,6 @@ interface LocalResolver {
 //#region src/ConfidenceServerProviderLocal.d.ts
 interface ProviderOptions {
   flagClientSecret: string;
-  apiClientId: string;
-  apiClientSecret: string;
   initializeTimeout?: number;
   flushInterval?: number;
   fetch?: typeof fetch;
@@ -250,8 +286,6 @@ declare class ConfidenceServerProviderLocal implements Provider {
   private extractValue;
   updateState(signal?: AbortSignal): Promise<void>;
   flush(signal?: AbortSignal): Promise<void>;
-  private fetchResolveStateUri;
-  private fetchToken;
   private static convertReason;
   private static convertEvaluationContext;
   /** Resolves with an evaluation of a Boolean flag */