npm package: @stagewise/companion-sdk
Description: Companion SDK for stagewise
Author: tiq UG
Latest version: 1.1.1

<img src="https://legacy.stagewise.io/static_mail/logo_with_text.png" alt="stagewise" width="160" />

# stagewise Companion SDK

With [stagewise](https://legacy.stagewise.io/) you can collect augmented feedback and bug reports from testers and stakeholders directly on your web app. Transform feedback into issues with one-click and deliver web apps faster.

The [Companion SDK](https://www.npmjs.com/package/@stagewise/companion-sdk) enables you to extend the functionality of the companion, for example by providing custom metadata for created findings.

<br/>
<div style="padding: 1rem; border: 1px solid hsl(60 100% 40%); border-radius: 1rem; background-color: hsl(60 100% 40% / 0.1);">
<span style="font-size: 2rem">🚨</span><br/>This SDK uses browser APIs and thus is only prepared for client-side rendered applications. If you use server-side rendering / RSC / etc. make sure that the functions provided in this SDK are part of the client-side bundle and only executed in the client environment.<br/>To check if the code is executed client side, it should be sufficient to check for the existence of the global `window` object.
</div>
<br/>

## Installation

For the latest stable version:

```bash
npm install @stagewise/companion-sdk
```

## Documentation

### Configure the companion

The SDK sets the ID of the workspace you link to the app and the behavior of the companion.

#### `setCompanionConfig`

```typescript
setCompanionConfig(config: CompanionConfig) => void
```

Update the config for the companion.

Whenever you set a new config, the companion automatically applies the changes immediately.

#### `getCompanionConfig`

```typescript
getCurrentConfig() => (CompanionConfig | undefined)
```

Get the currently active config for the companion.

If the companion is not loaded and no config was set, the function returns `undefined`.

### Add custom metadata to findings

The SDK allows you to extend the collected metadata upon creation of a finding with further entries like User IDs and more.

#### `registerMetadataGetter`

```typescript
registerMetadataGetter(metadata: (() => Record<string, unknown> | Promise<Record<string, unknown>>))
                        => number
```

Register a custom metadata getter. This function is used to provide custom metadata to the SDK.
The getter is called every time a finding is created and the returned data is added to the `custom` field of the finding metadata.

You may register more than one getter in your function, and all of them will be called and their data will be merged.

_Make sure that the getter returns data with unique keys, since the companion will flat-merge the data from all registered getters and no order is guaranteed. When registering multiple metadata getters, we recommand inserting each data from a getter in it's own unique top-level key._

#### `unregisterMetadataGetter`

```typescript
unregisterMetadataGetter(handle: number) => boolean
```

Unregister a custom metadata getter. May be used when i.e. leaving a page or when a component in react is re-rendered.

### Example - React application

The following implementation will attach an imaginary `userId` to each finding's metadata, as long as the component `Component` has been mounted before the finding-creation:

```typescript
import { registerMetadataGetter, unregisterMetadataGetter } from "@stagewise/companion-sdk";
import { useEffect } from "react";
import { getUserId } from "your-auth-package"

export function Component(){
    useEffect(() => {
        const getterHandle = registerMetadataGetter(() => {
            return {
                userId: getUserId()
            }
        });

        return () => {
            unregisterMetadataGetter(getterHandle);
        }
    }, [])

    return (<div> Hello Companion SDK! </div>)
}
```