docs: Revamp readme

README.md

@@ -6,13 +6,81 @@ JavaScript implementation of the [Confidence](https://confidence.spotify.com/) S
 
 # Usage
 
+We recommend to try out Confidence using the vanilla [sdk](packages/sdk/README.md). The setup guide below will help you get started.
+
 This monorepo exports multiple packages, with their own docs:
 
+- [sdk](packages/sdk/README.md)
+- [react](packages/react/README.md)
 - [openfeature-web-provider](packages/openfeature-web-provider/README.md)
 - [openfeature-server-provider](packages/openfeature-server-provider/README.md)
-- [sdk](packages/sdk/README.md)
 
-# Development
+## SDK setup
+
+### Adding the dependencies
+
+To add the packages to your dependencies run:
+
+```sh
+yarn add @spotify-confidence/sdk
+```
+
+### Initializing the SDK
+
+Run the `Confidence.create` function to obtain a root instance of `Confidence`.
+
+The SDK initialization requires an API key (`clientSecret`) to work. This key obtained through the [Confidence console](https://app.confidence.spotify.com/).
+
+```ts
+import { Confidence } from '@spotify-confidence/sdk';
+
+const confidence = Confidence.create({
+  clientSecret: 'mysecret',
+  region: 'eu', // or 'us'
+  environment: 'client', // or 'server'
+  timeout: 1000,
+});
+```
+
+### Setting the context
+
+You can set the context manually by using `setContext({})` or obtain a "child instance" of Confidence with a modified context by using `withContext({})`.
+
+```ts
+confidence.setContext({ 'pants-color': 'yellow' });
+const childInstance = confidence.withContext({ 'pants-color': 'blue', 'pants-fit': 'slim' });
+```
+
+> [!IMPORTANT]
+> When using the SDK in a server environment, you should call `withContext` rather than `setContext`. This will give you a new instance scoped to the request and prevent context from leaking between requests.
+
+### Accessing flags
+
+The flag value API returns the Confidence assigned flag value or the passed in default value if no value was returned.
+The API supports dot notation, meaning that if the Confidence flag has a property `enabled` on the flag, you can access it directly.
+
+```ts
+const flag = await confidence.getFlag('tutorial-feature', {});
+if (flag.enabled) {
+  // ship it!
+}
+// or
+const enabled = await confidence.getFlag('tutorial-feature.enabled', false);
+if (enabled) {
+  // ship it!
+}
+```
+
+> [!TIP]
+> If you are troubleshooting flag values, the flag evaluation API can be really useful since it returns a `FlagEvaluation` type that contain information about `variant`, `reason` and possible error details.
+
+```ts
+const flagEvaluation = await confidence.evaluateFlag('tutorial-feature', {});
+```
+
+# Contributions and Development
+
+We'd love to get patches from you! See [Contributing](CONTRIBUTING.md) for details.
 
 ## Setup
 
@@ -52,7 +120,7 @@ Before release the sources (and types) are bundled. This process also includes g
 If you intend to change the public API you need to run the bundle command locally and commit the changed API report files, otherwise the commit will fail in CI. To update the API report run:
 
 ```sh
-yarn bundle
+yarn bundle --local
 ```
 
 ## Example apps

examples/node/package.json

@@ -6,9 +6,6 @@
   "type": "module",
   "license": "MIT",
   "dependencies": {
-    "@openfeature/core": "^1.1.0",
-    "@openfeature/server-sdk": "^1.13.5",
-    "@spotify-confidence/openfeature-server-provider": "workspace:*",
     "@spotify-confidence/sdk": "workspace:*"
   },
   "scripts": {

examples/node/src/index.js

@@ -5,18 +5,14 @@ if (!process.env.CLIENT_SECRET) {
 }
 const confidence = Confidence.create({
   clientSecret: process.env.CLIENT_SECRET,
-  fetchImplementation: fetch,
   timeout: 1000,
   logger: console,
 });
 main();
 
 async function main() {
-  confidence.subscribe(state => console.log('state:', state));
-  confidence.setContext({ targeting_key: 'user-a' });
-  const fe = confidence.evaluateFlag('tutorial-feature.title', 'Default');
-
+  console.log('Starting example');
+  const fe = confidence.withContext({ targeting_key: 'user-a' }).evaluateFlag('tutorial-flag', {});
   console.log(fe);
-
   console.log(await fe);
 }

packages/sdk/README.md

@@ -32,14 +32,7 @@ const confidence = Confidence.create({
 ### Region
 
 The region option is used to set the region for the network request to the Confidence backend. When the region is not set, the default (global) region will be used.
-The current regions are: `eu` and `us`, the region can be set as follows:
-
-```ts
-const provider = createConfidenceWebProvider({
-  region: 'eu', // or 'us'
-  // ... other options
-});
-```
+The current regions are: `eu` and `us`.
 
 ### Timeout
 
@@ -64,6 +57,32 @@ At this point, the context of `childInstance` is `'pants-color': 'blue', 'pants-
 > [!IMPORTANT]
 > When using the SDK in a server environment, you should call `withContext` rather than `setContext`. This will give you a new instance scoped to the request and prevent context from leaking between requests.
 
+## Accessing flags
+
+Flags can be accessed with two different API's.
+
+The flag value API returns the Confidence assigned flag value or the passed in default value if no value was returned.
+The evaluate API returns a `FlagEvaluation` type that also contain information about `variant`, `reason` and possible error details.
+
+```ts
+const flag = await confidence.getFlag('tutorial-feature', {});
+const flagEvaluation = await confidence.evaluateFlag('tutorial-feature', {});
+```
+
+### Dot notation
+
+Both the "flag value", and the "evaluate" API's support dot notation, meaning that if the Confidence flag has a property `enabled` or `title` on the flag, you can access them directly:
+
+```ts
+const enabled = await confidence.getFlag('tutorial-feature.enabled', false);
+const messageEvaluation = await confidence.evaluateFlag('tutorial-feature.message', 'default message');
+const message = messageEvaluation.value;
+```
+
+### Synchronous access
+
+In a client application (where `environment` is set to `client`), the SDK fetches and caches all flags when the context is updated. This means the flags can be accessed synchronously after that.
+
 ## Event tracking
 
 Use `confidence.track()` from any Confidence instance to track an event in Confidence. Any context data set on the instance will be appended to the tracking event.

yarn.lock

@@ -13006,9 +13006,6 @@ __metadata:
   version: 0.0.0-use.local
   resolution: "node-example@workspace:examples/node"
   dependencies:
-    "@openfeature/core": "npm:^1.1.0"
-    "@openfeature/server-sdk": "npm:^1.13.5"
-    "@spotify-confidence/openfeature-server-provider": "workspace:*"
     "@spotify-confidence/sdk": "workspace:*"
   languageName: unknown
   linkType: soft