@screeb/sdk-react 0.1.0

package/docs/README.md

@@ -0,0 +1,637 @@
+@screeb/sdk-react
+
+# @screeb/sdk-react
+
+## Table of contents
+
+### Type Aliases
+
+- [CloseFunction](README.md#closefunction)
+- [DebugFunction](README.md#debugfunction)
+- [EventTrackFunction](README.md#eventtrackfunction)
+- [IdentityFunction](README.md#identityfunction)
+- [IdentityGetFunction](README.md#identitygetfunction)
+- [IdentityGroupAssignFunction](README.md#identitygroupassignfunction)
+- [IdentityGroupUnassignFunction](README.md#identitygroupunassignfunction)
+- [IdentityPropertiesFunction](README.md#identitypropertiesfunction)
+- [IdentityResetFunction](README.md#identityresetfunction)
+- [InitFunction](README.md#initfunction)
+- [LoadFunction](README.md#loadfunction)
+- [ScreebContextValues](README.md#screebcontextvalues)
+- [ScreebProps](README.md#screebprops)
+- [ScreebProviderProps](README.md#screebproviderprops)
+- [SurveyCloseFunction](README.md#surveyclosefunction)
+- [SurveyStartFunction](README.md#surveystartfunction)
+- [TargetingCheckFunction](README.md#targetingcheckfunction)
+- [TargetingDebugFunction](README.md#targetingdebugfunction)
+
+### Functions
+
+- [ScreebProvider](README.md#screebprovider)
+- [useScreeb](README.md#usescreeb)
+
+## Type Aliases
+
+### CloseFunction
+
+Ƭ **CloseFunction**: () => `Promise`<`void`\>
+
+#### Type declaration
+
+▸ (): `Promise`<`void`\>
+
+Shutdowns current Screeb session.
+
+**`Example`**
+
+```ts
+const { close } = useScreeb();
+
+close();
+```
+
+##### Returns
+
+`Promise`<`void`\>
+
+___
+
+### DebugFunction
+
+Ƭ **DebugFunction**: () => `Promise`<`unknown`\>
+
+#### Type declaration
+
+▸ (): `Promise`<`unknown`\>
+
+Prints the actual state information of Screeb tag.
+
+**`Example`**
+
+```ts
+const { debug } = useScreeb();
+
+debug();
+// ******************* SCREEB SESSION DEBUG *********************
+// Screeb channel id: <UUID>
+// Screeb channel type: widget
+// Screeb respondent id: <UUID>
+// Screeb survey id: none
+// Screeb response id: none
+//
+// Screeb current session start: Thu May 04 2023 16:53:49 GMT+0200 (Central European Summer Time)
+// Screeb current session last activity: Thu May 04 2023 17:41:30 GMT+0200 (Central European Summer Time)
+//
+// Screeb targeting engine status: disabled
+// Screeb targeting engine: 3 surveys
+//
+// Detected platform: desktop
+// Detected locale: en-GB
+// Detected timezone: -120
+// **************************************************************
+```
+
+##### Returns
+
+`Promise`<`unknown`\>
+
+___
+
+### EventTrackFunction
+
+Ƭ **EventTrackFunction**: (`eventName`: `string`, `eventProperties?`: `PropertyRecord`) => `Promise`<`unknown`\>
+
+#### Type declaration
+
+▸ (`eventName`, `eventProperties?`): `Promise`<`unknown`\>
+
+Tracks a user event.
+
+**`Example`**
+
+```ts
+const { eventTrack } = useScreeb();
+
+eventTrack(
+  "Product added to cart",
+  {
+    product_name: 'Red bike 2021',
+    category: 'sport',
+    color: 'red',
+    price: 299,
+    count: 1,
+    reference: '2CF093TG1',
+    delivery_method: 'UPS',
+    user_logged: false,
+    added_at: new Date(),
+  }
+);
+```
+
+##### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `eventName` | `string` | The event name. |
+| `eventProperties?` | `PropertyRecord` | The properties of your event. ```text Requirements: - Property names must be limited to 128 characters - No more than 1000 attributes - Supported types for values: string, number, boolean and Date. ``` |
+
+##### Returns
+
+`Promise`<`unknown`\>
+
+___
+
+### IdentityFunction
+
+Ƭ **IdentityFunction**: (`userId`: `string`, `userProperties?`: `PropertyRecord`) => `Promise`<`unknown`\>
+
+#### Type declaration
+
+▸ (`userId`, `userProperties?`): `Promise`<`unknown`\>
+
+Change the current user identity.
+Warning: Running surveys will be closed.
+
+**`Example`**
+
+```ts
+const { identity } = useScreeb();
+
+identity(
+  "<your-user-id>",
+  {
+    firstname: '<user-firstname>',
+    lastname: '<user-lastname>',
+    plan: '<user-plan>',
+    last_seen_at: new Date(),
+    authenticated: true
+  }
+);
+```
+
+##### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `userId` | `string` | The unique identifier of your user. |
+| `userProperties?` | `PropertyRecord` | The properties of your user. ```text Requirements: - Property names must be limited to 128 characters - No more than 1000 attributes - Supported types for values: string, number, boolean and Date. ``` |
+
+##### Returns
+
+`Promise`<`unknown`\>
+
+___
+
+### IdentityGetFunction
+
+Ƭ **IdentityGetFunction**: () => `Promise`<`ScreebIdentityGetReturn`\>
+
+#### Type declaration
+
+▸ (): `Promise`<`ScreebIdentityGetReturn`\>
+
+Retrieves the current user identity.
+
+**`Example`**
+
+```ts
+const { identityGet } = useScreeb();
+
+console.log(await identityGet());
+// {
+//   anonymous_id: "<UUID>",
+//   user_id: "<UUID>",
+//   session_id: "<UUID>",
+//   session_start: "2023-05-04T16:30:15.882Z",
+//   session_end: "2023-05-04T17:02:09.087Z",
+//   channel_id: "<UUID>",
+//   is_ready: true,
+// }
+```
+
+##### Returns
+
+`Promise`<`ScreebIdentityGetReturn`\>
+
+___
+
+### IdentityGroupAssignFunction
+
+Ƭ **IdentityGroupAssignFunction**: (`groupName`: `string`, `groupType?`: `string`, `groupProperties?`: `PropertyRecord`) => `Promise`<`unknown`\>
+
+#### Type declaration
+
+▸ (`groupName`, `groupType?`, `groupProperties?`): `Promise`<`unknown`\>
+
+Assigns the current user to a group.
+
+**`Example`**
+
+```ts
+const { identityGroupAssign } = useScreeb();
+
+identityGroupAssign(
+  'company',
+  'Apple',
+  {
+    address_line_1: 'Apple Campus',
+    address_line_2: '1 Infinite Loop',
+    city: 'Cupertino',
+    zipcode: 95014,
+    state: 'California',
+    country: 'United states',
+  }
+);
+```
+
+##### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `groupName` | `string` |  |
+| `groupType?` | `string` |  |
+| `groupProperties?` | `PropertyRecord` | The properties of your user group. ```text Requirements: - Property names must be limited to 128 characters - No more than 1000 attributes - Supported types for values: string, number, boolean and Date. ``` |
+
+##### Returns
+
+`Promise`<`unknown`\>
+
+___
+
+### IdentityGroupUnassignFunction
+
+Ƭ **IdentityGroupUnassignFunction**: (`groupName`: `string`, `groupType?`: `string`) => `Promise`<`unknown`\>
+
+#### Type declaration
+
+▸ (`groupName`, `groupType?`): `Promise`<`unknown`\>
+
+Unassigns the current user to a group.
+
+**`Example`**
+
+```ts
+const { identityGroupUnassign } = useScreeb();
+
+identityGroupUnassign('company', 'Apple');
+```
+
+##### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `groupName` | `string` | The name of your user group. |
+| `groupType?` | `string` | The type of your user group. |
+
+##### Returns
+
+`Promise`<`unknown`\>
+
+___
+
+### IdentityPropertiesFunction
+
+Ƭ **IdentityPropertiesFunction**: (`userProperties`: `PropertyRecord`) => `Promise`<`unknown`\>
+
+#### Type declaration
+
+▸ (`userProperties`): `Promise`<`unknown`\>
+
+Adds properties to the current user identity.
+
+**`Example`**
+
+```ts
+const { identityProperties } = useScreeb();
+
+// Set user properties
+identityProperties(
+  {
+    firstname: '<user-firstname>',
+    lastname: '<user-lastname>',
+    plan: '<user-plan>',
+    last_seen_at: new Date(),
+    authenticated: true
+  }
+);
+
+// Delete user property : set values to null
+identityProperties(
+  {
+    age: null,
+    company: null,
+    logged: true,
+  }
+);
+```
+
+##### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `userProperties` | `PropertyRecord` | The properties of your user. ```text Requirements: - Property names must be limited to 128 characters - No more than 1000 attributes - Supported types for values: string, number, boolean and Date. ``` |
+
+##### Returns
+
+`Promise`<`unknown`\>
+
+___
+
+### IdentityResetFunction
+
+Ƭ **IdentityResetFunction**: () => `Promise`<`unknown`\>
+
+#### Type declaration
+
+▸ (): `Promise`<`unknown`\>
+
+Resets the current user identity.
+Warning: This command must be called only once, since it creates a new identity on Screeb side.
+
+**`Example`**
+
+```ts
+const { identityReset } = useScreeb();
+
+identityReset();
+```
+
+##### Returns
+
+`Promise`<`unknown`\>
+
+___
+
+### InitFunction
+
+Ƭ **InitFunction**: (`websiteId`: `string`, `userId?`: `string`, `userProperties?`: `PropertyRecord`) => `Promise`<`void`\>
+
+#### Type declaration
+
+▸ (`websiteId`, `userId?`, `userProperties?`): `Promise`<`void`\>
+
+Initializes Screeb tag.
+
+**`Example`**
+
+```ts
+const { init } = useScreeb();
+
+init(
+  "<your-website-id>",
+  "<your-user-id>",
+  {
+    firstname: '<user-firstname>',
+    lastname: '<user-lastname>',
+    plan: '<user-plan>',
+    last_seen_at: new Date(),
+    authenticated: true
+  }
+);
+```
+
+##### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `websiteId` | `string` | Your website/channel id. |
+| `userId?` | `string` | The unique identifier of your user. |
+| `userProperties?` | `PropertyRecord` | The properties of your user. ```text Requirements: - Property names must be limited to 128 characters - No more than 1000 attributes - Supported types for values: string, number, boolean and Date ``` |
+
+##### Returns
+
+`Promise`<`void`\>
+
+___
+
+### LoadFunction
+
+Ƭ **LoadFunction**: (`options?`: `ScreebOptions`) => `Promise`<`void`\>
+
+#### Type declaration
+
+▸ (`options?`): `Promise`<`void`\>
+
+Appends Screeb tag into your dom.
+
+**`Example`**
+
+```ts
+const { load } = useScreeb();
+
+load();
+```
+
+##### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `options?` | `ScreebOptions` | Screeb module options. |
+
+##### Returns
+
+`Promise`<`void`\>
+
+___
+
+### ScreebContextValues
+
+Ƭ **ScreebContextValues**: `Object`
+
+Screeb context API
+
+#### Type declaration
+
+| Name | Type |
+| :------ | :------ |
+| `close` | [`CloseFunction`](README.md#closefunction) |
+| `debug` | [`DebugFunction`](README.md#debugfunction) |
+| `eventTrack` | [`EventTrackFunction`](README.md#eventtrackfunction) |
+| `identity` | [`IdentityFunction`](README.md#identityfunction) |
+| `identityGet` | [`IdentityGetFunction`](README.md#identitygetfunction) |
+| `identityGroupAssign` | [`IdentityGroupAssignFunction`](README.md#identitygroupassignfunction) |
+| `identityGroupUnassign` | [`IdentityGroupUnassignFunction`](README.md#identitygroupunassignfunction) |
+| `identityProperties` | [`IdentityPropertiesFunction`](README.md#identitypropertiesfunction) |
+| `identityReset` | [`IdentityResetFunction`](README.md#identityresetfunction) |
+| `init` | [`InitFunction`](README.md#initfunction) |
+| `load` | [`LoadFunction`](README.md#loadfunction) |
+| `surveyClose` | [`SurveyCloseFunction`](README.md#surveyclosefunction) |
+| `surveyStart` | [`SurveyStartFunction`](README.md#surveystartfunction) |
+| `targetingCheck` | [`TargetingCheckFunction`](README.md#targetingcheckfunction) |
+| `targetingDebug` | [`TargetingDebugFunction`](README.md#targetingdebugfunction) |
+
+___
+
+### ScreebProps
+
+Ƭ **ScreebProps**: `Object`
+
+Properties of Screeb provider
+
+#### Type declaration
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `userId?` | `string` | The unique identifier of your user. |
+| `userProperties?` | `PropertyRecord` | The properties of your user. |
+| `websiteId` | `string` | Your website/channel id. |
+
+___
+
+### ScreebProviderProps
+
+Ƭ **ScreebProviderProps**: { `autoInit?`: `boolean` ; `options?`: `ScreebOptions` ; `shouldLoad?`: `boolean`  } & `Partial`<[`ScreebProps`](README.md#screebprops)\>
+
+Properties of Screeb provider
+
+___
+
+### SurveyCloseFunction
+
+Ƭ **SurveyCloseFunction**: () => `Promise`<`unknown`\>
+
+#### Type declaration
+
+▸ (): `Promise`<`unknown`\>
+
+Interrupts a running survey.
+
+**`Example`**
+
+```ts
+const { surveyClose } = useScreeb();
+
+surveyClose();
+```
+
+##### Returns
+
+`Promise`<`unknown`\>
+
+___
+
+### SurveyStartFunction
+
+Ƭ **SurveyStartFunction**: (`surveyId`: `string`, `allowMultipleResponses`: `boolean`, `hiddenFields`: `PropertyRecord`) => `Promise`<`unknown`\>
+
+#### Type declaration
+
+▸ (`surveyId`, `allowMultipleResponses`, `hiddenFields`): `Promise`<`unknown`\>
+
+Starts a survey by its ID.
+
+**`Example`**
+
+```ts
+const { surveyStart } = useScreeb();
+
+surveyStart(
+  '<UUID>',
+  false,
+  {
+    color: "green",
+    article_id: 42
+  }
+);
+```
+
+##### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `surveyId` | `string` |
+| `allowMultipleResponses` | `boolean` |
+| `hiddenFields` | `PropertyRecord` |
+
+##### Returns
+
+`Promise`<`unknown`\>
+
+___
+
+### TargetingCheckFunction
+
+Ƭ **TargetingCheckFunction**: () => `Promise`<`unknown`\>
+
+#### Type declaration
+
+▸ (): `Promise`<`unknown`\>
+
+Forces a targeting check.
+
+**`Example`**
+
+```ts
+const { targetingCheck } = useScreeb();
+
+targetingCheck();
+```
+
+##### Returns
+
+`Promise`<`unknown`\>
+
+___
+
+### TargetingDebugFunction
+
+Ƭ **TargetingDebugFunction**: () => `Promise`<`unknown`\>
+
+#### Type declaration
+
+▸ (): `Promise`<`unknown`\>
+
+Prints the current state of the targeting engine.
+
+**`Example`**
+
+```ts
+const { targetingDebug } = useScreeb();
+
+console.log(await targetingDebug());
+// targeting ************ SCREEB TARGETING RULES DEBUG **************
+// Disabled surveys are not listed here.
+//
+// Screeb channel id: <UUID>
+// Screeb respondent id: <UUID>
+//
+// Survey <UUID>:
+// https://admin.screeb.app/org/last/survey/<UUID>/share
+//
+//   - Rule of type "Device type (desktop/mobile/tablet)": true 🟢
+//   - Rule of type "Multiple display": true 🟢
+//   - Rule of type "Capping per time between survey display on current respondent": true 🟢
+//   - Rule of type "User event count": false 🔴
+//   - Rule of type "Capping per respondent display count": false 🔴
+```
+
+##### Returns
+
+`Promise`<`unknown`\>
+
+## Functions
+
+### ScreebProvider
+
+▸ **ScreebProvider**(`props`, `context?`): ``null`` \| `ReactElement`<`any`, `any`\>
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `props` | `PropsWithChildren`<[`ScreebProviderProps`](README.md#screebproviderprops)\> |
+| `context?` | `any` |
+
+#### Returns
+
+``null`` \| `ReactElement`<`any`, `any`\>
+
+___
+
+### useScreeb
+
+▸ **useScreeb**(): [`ScreebContextValues`](README.md#screebcontextvalues)
+
+#### Returns
+
+[`ScreebContextValues`](README.md#screebcontextvalues)

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@screeb/sdk-react",
+  "version": "0.1.0",
+  "description": "Screeb's browser sdk, optimized for React.",
+  "keywords": [
+    "product discovery",
+    "product management",
+    "survey",
+    "analytics",
+    "user feedback",
+    "user voice",
+    "user research"
+  ],
+  "homepage": "https://screeb.app",
+  "bugs": {
+    "url": "https://github.com/ScreebApp/sdk-js/issues",
+    "email": "suuport@screeb.app"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ScreebApp/sdk-js.git",
+    "directory": "packages/screeb-sdk-react"
+  },
+  "license": "MIT",
+  "author": "Screeb's frontend team",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "import": "./dist/es/index.js"
+    }
+  },
+  "module": "dist/es/index.js",
+  "types": "dist/es/index.d.ts",
+  "files": [
+    "dist",
+    "docs",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "rollup -c ./node_modules/@screeb/typescript-config/src/rollup.config.js",
+    "build:doc": "typedoc src/index.ts",
+    "clean": "rm -Rf dist",
+    "lint": "eslint .",
+    "test": "echo '@TODO'"
+  },
+  "devDependencies": {
+    "@screeb/eslint-config": "^0.1.4",
+    "@screeb/sdk-browser": "^0.1.6",
+    "@screeb/typescript-config": "^0.1.4",
+    "@types/jest": "^29.5.1",
+    "@types/node": "^18.11.19",
+    "@types/react": "^18.0.20",
+    "@types/react-dom": "^18.0.6",
+    "@typescript-eslint/eslint-plugin": "^5.59.6",
+    "eslint": "^8.41.0",
+    "eslint-plugin-import": "^2.27.5",
+    "eslint-plugin-jest": "^27.2.1",
+    "eslint-plugin-jsx-a11y": "^6.7.1",
+    "eslint-plugin-prettier": "^4.2.1",
+    "jest": "^29.5.0",
+    "prettier": "^2.8.8",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "rollup": "^3.23.0",
+    "typedoc": "^0.24.7",
+    "typedoc-plugin-markdown": "^3.15.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@screeb/sdk-browser": "^0.1.7"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0"
+  }
+}