Bump SDK to v0.8 (#115)

README.md

@@ -138,6 +138,7 @@ The following references provide guidance to help you get started, integrate, an
 - [Patch Reference](docs/patch.md)
 - [User Reference](docs/user.md)
 - [Session Reference](docs/session.md)
+- [Testing](docs/testing.md)
 - [Troubleshooting](docs/troubleshooting.md)
 
 If you are new to the Croct platform, the [quick start guide](docs/quick-start.md) is a good starting point for 

docs/plug.md

@@ -41,7 +41,8 @@ These are the currently supported options:
 | Option                  | Type         | Required | Default Value | Description                                                                                                                                                                                               |
 |-------------------------|--------------|----------|---------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | `appId`                 | string       | Depends  | None          | The ID of the application you set up on Croct. This option is required unless you have loaded the SDK using a HTML snippet that already specifies the application ID.                                     |
-| `debug`                 | boolean      | No       | `false`       | If `true`, turns on debug mode, which logs helpful messages to the console.                                                                                                                               |
+| `debug`                 | boolean      | No       | `false`       | If `true`, turns on debug mode, which logs helpful messages to the console. See [Testing](testing.md#debug-mode) for more details.                                                                        |
+| `test`                  | boolean      | No       | `false`       | If `true`, enables the test mode. See [Testing](testing.md#test-mode) for more details.                                                                                                                   |
 | `track`                 | boolean      | No       | `true`        | If `true`, enables the automatic event tracking on initialization.                                                                                                                                        |
 | `token`                 | string\|null | No       | None          | The JWT token issued by Croct. If `null`, clears any token specified on previous calls.                                                                                                                   |
 | `userId`                | string       | No       | None          | The ID of the user logged into the application. Internally, the SDK will issue a token using the specified ID as the subject claim of the token. The `token` and `userId` options are mutually exclusive. |

docs/testing.md

@@ -0,0 +1,109 @@
+# Testing
+
+For an enhanced developer experience, the SDK provides both debug and test modes to assist you with testing.
+
+## Debug mode
+
+The debug mode enables fine-grained logging to help developers detect and diagnose issues with the integration.
+Each log receives a severity level, so you can filter the log output to only see the log messages you 
+care about.
+
+The severity levels and their respective meanings are:
+
+- 🧐 **Debug**  
+  Fine-grained messages that provide context to understand the steps leading to errors and warnings.
+- 🤓 **Info**  
+  Informational messages that highlight the SDK's state and progress.
+- 🤔 **Warning**  
+  Warnings about potential issues that might be problems or might not.
+- 😱 **Error**  
+  Abnormal or unexpected behaviors that need attention.
+
+### Enabling debug mode
+
+To enable the debug mode, you need to set `debug` to true when initializing the SDK:
+
+```ts
+croct.plug({debug: true});
+```
+
+You can now check the console output at runtime for the debug logs.
+
+## Test mode
+
+The test mode enables the SDK to track events in test environments to ensure that the integration is working 
+as expected. It works by replacing the actual transport layer with a fake one to simulate successful calls.
+
+### Enabling test mode
+
+> ✨ If you use Jest or any other testing framework that sets the `NODE_ENV=test`, it should just work out of the box 
+> without any additional configuration.
+
+By default, the SDK automatically detects test environments based on the `NODE_ENV`. To explicitly enable or disable 
+the test mode, you can either:
+
+- Pass `test` as `true` when initializing the SDK
+- Set the `CROCT_TEST_MODE` environment variable to `true`
+
+The order of precedence is as follows:
+
+1. If the `test` option is passed, that overrides any other environment settings
+2. If the `CROCT_TEST_MODE` environment variable is set, that takes precedence over the automatic detection of 
+test environments
+3. If neither `test` nor `CROCT_TEST_MODE` is set, the SDK detects the test environment automatically based on
+the `NODE_ENV`
+
+### Testing events
+
+The SDK tracks an event for every operation executed on the server side.
+
+For example, executing the code below will trigger the `userProfileChanged` event with changes to the user profile:
+
+```ts
+croct.user.edit()
+   .add('interest', 'tests')
+   .save()
+```
+
+This flexible design allows you to listen to events and test your integration easily.
+
+Let's take the previous code as an example. You can check if your integration is working as expected by listening to 
+the `userProfileChanged` event as follows:
+
+```ts
+import {EventListener, EventInfo} from '@croct/plug/sdk/tracking';
+
+test('should add an interest to the user profile', async () => {
+    await croct.plug({
+        appId: '00000000-0000-0000-0000-000000000000',
+    });
+
+    const listener: EventListener = jest.fn();
+
+    croct.tracker.addListener(listener);
+
+    await croct.user.edit()
+        .add('interest', 'tests')
+        .save();
+
+    expect(listener).toHaveBeenCalledWith(
+        expect.objectContaining<Partial<EventInfo<'userProfileChanged'>>>({
+            status: 'confirmed',
+            event: {
+                type: 'userProfileChanged',
+                patch: {
+                    operations: [
+                        {
+                            path: 'interest',
+                            type: 'add',
+                            value: 'tests',
+                        },
+                    ],
+                },
+            },
+        }),
+    );
+})
+```
+
+See the [Event reference](events.md) for the list of events triggered by the SDK. 

package.json

@@ -33,7 +33,7 @@
     "bundle": "rollup -c"
   },
   "dependencies": {
-    "@croct/sdk": "^0.7.0",
+    "@croct/sdk": "^0.8.0",
     "tslib": "^2.2.0"
   },
   "devDependencies": {

src/plug.ts

@@ -124,11 +124,16 @@ export class GlobalPlug implements Plug {
             );
         }
 
-        const {plugins, ...sdkConfiguration} = configuration;
+        const {plugins, test, ...sdkConfiguration} = configuration;
 
         const sdk = SdkFacade.init({
             ...sdkConfiguration,
             appId: appId,
+            test: test ?? (typeof process === 'object' && (
+                process.env?.CROCT_TEST_MODE !== undefined
+                    ? process.env.CROCT_TEST_MODE === 'true'
+                    : process.env?.NODE_ENV === 'test'
+            )),
         });
 
         this.instance = sdk;

src/sdk/tracking.ts

@@ -1,9 +1,14 @@
+import {EventInfo as SdkEventInfo} from '@croct/sdk/tracker';
+import {TrackingEvent, TrackingEventType} from '@croct/sdk/trackingEvents';
+
 export {TrackerFacade} from '@croct/sdk/facade/trackerFacade';
-export {EventInfo, EventListener} from '@croct/sdk/tracker';
+export {EventListener} from '@croct/sdk/tracker';
 export {
     TrackingEvent,
     TrackingEventType,
     ExternalTrackingEvent,
     ExternalTrackingEventPayload,
     ExternalTrackingEventType,
 } from '@croct/sdk/trackingEvents';
+
+export type EventInfo<T extends TrackingEventType> = SdkEventInfo<TrackingEvent<T>>;