@staffbase/widget-sdk 3.3.1 → 3.4.0-beta.1

package/docs/Interface: SBUserAvatar.md

@@ -0,0 +1,27 @@
+# Interface: SBUserAvatar
+
+User avatar definition
+
+## Properties
+
+### icon
+
+• **icon**: [*SBImageEntity*](../wiki/Interface:%20SBImageEntity)
+
+___
+
+### original
+
+• **original**: [*SBImageEntity*](../wiki/Interface:%20SBImageEntity)
+
+___
+
+### publicID
+
+• **publicID**: *string*
+
+___
+
+### thumb
+
+• **thumb**: [*SBImageEntity*](../wiki/Interface:%20SBImageEntity)

package/docs/Interface: SBUserProfile.md

@@ -0,0 +1,51 @@
+# Interface: SBUserProfile
+
+User profile data
+
+## Properties
+
+### avatar
+
+• `Optional` **avatar**: [*SBUserAvatar*](../wiki/Interface:%20SBUserAvatar)
+
+___
+
+### department
+
+• `Optional` **department**: *string*
+
+___
+
+### firstName
+
+• **firstName**: *string*
+
+___
+
+### lastName
+
+• **lastName**: *string*
+
+___
+
+### location
+
+• `Optional` **location**: *string*
+
+___
+
+### phoneNumber
+
+• `Optional` **phoneNumber**: *string*
+
+___
+
+### position
+
+• `Optional` **position**: *string*
+
+___
+
+### publicEmailAddress
+
+• `Optional` **publicEmailAddress**: *string*

package/docs/Interface: UserListItem.md

@@ -0,0 +1,27 @@
+# Interface: UserListItem
+
+Single user item
+
+## Properties
+
+### entityType
+
+• `Optional` **entityType**: *string*
+
+___
+
+### firstName
+
+• `Optional` **firstName**: *string*
+
+___
+
+### id
+
+• `Optional` **id**: *string*
+
+___
+
+### lastName
+
+• `Optional` **lastName**: *string*

package/docs/Interface: UserListRequestQuery.md

@@ -0,0 +1,27 @@
+# Interface: UserListRequestQuery
+
+User list request parameters
+
+## Properties
+
+### filter
+
+• `Optional` **filter**: *string*
+
+___
+
+### limit
+
+• `Optional` **limit**: *number*
+
+___
+
+### offset
+
+• `Optional` **offset**: *number*
+
+___
+
+### sort
+
+• `Optional` **sort**: [*UserListSorting*](../wiki/Home#userlistsorting)

package/docs/Interface: UserListResponse.md

@@ -0,0 +1,27 @@
+# Interface: UserListResponse
+
+Responded user list
+
+## Properties
+
+### data
+
+• **data**: [*UserListItem*](../wiki/Interface:%20UserListItem)[]
+
+___
+
+### limit
+
+• **limit**: *number*
+
+___
+
+### offset
+
+• **offset**: *number*
+
+___
+
+### total
+
+• **total**: *number*

package/docs/Interface: WidgetApi.md

@@ -0,0 +1,75 @@
+# Interface: WidgetApi
+
+Widget API class.
+
+A class providing access to additional information about the Staffbase ecosystem for widgets.
+
+## Methods
+
+### getLegacyAppTheme
+
+▸ **getLegacyAppTheme**(): [*ColorTheme*](../wiki/Interface:%20ColorTheme)
+
+Call to retrieve the color theme of the app. Since this theme definitions
+are currently redesigned, this method is called legacy.
+
+**Returns:** [*ColorTheme*](../wiki/Interface:%20ColorTheme)
+
+An object containing the color theme data is returned.
+
+___
+
+### getUserInformation
+
+▸ **getUserInformation**(`userId?`: *string*): *Promise*<[*SBUserProfile*](../wiki/Interface:%20SBUserProfile)\>
+
+Call to retrieve the user profile of the current or a specific user.
+
+#### Parameters:
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `userId?` | *string* | User ID to lookup for; leave blank to retrieve current user |
+
+**Returns:** *Promise*<[*SBUserProfile*](../wiki/Interface:%20SBUserProfile)\>
+
+A promise containing the SBUserProfile is returned. In case of an error,
+the promise is rejected.
+
+___
+
+### getUserInformationByExternalId
+
+▸ **getUserInformationByExternalId**(`externalId`: *string*): *Promise*<[*SBUserProfile*](../wiki/Interface:%20SBUserProfile)\>
+
+Call to retrieve a user profile by its external ID.
+
+#### Parameters:
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `externalId` | *string* | An external ID of the user that shall be returned |
+
+**Returns:** *Promise*<[*SBUserProfile*](../wiki/Interface:%20SBUserProfile)\>
+
+A promise containing the SBUserProfile is returned. In case of an error,
+the promise is rejected.
+
+___
+
+### getUserList
+
+▸ **getUserList**(`query`: [*UserListRequestQuery*](../wiki/Interface:%20UserListRequestQuery)): *Promise*<[*UserListResponse*](../wiki/Interface:%20UserListResponse)\>
+
+Call to retrieve a list of users determined by the query object.
+
+#### Parameters:
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `query` | [*UserListRequestQuery*](../wiki/Interface:%20UserListRequestQuery) | Adjust limit, offset, filter, and sorting for the request |
+
+**Returns:** *Promise*<[*UserListResponse*](../wiki/Interface:%20UserListResponse)\>
+
+A promise containing the UserListResponse is returned. In case of an error,
+the promise is rejected.

package/docs/_Sidebar.md

@@ -0,0 +1,20 @@
+## [@staffbase/widget-sdk](../wiki/Home)
+
+
+### Interfaces
+
+- [BaseBlock](../wiki/Interface:%20BaseBlock)
+- [BlockAttributes](../wiki/Interface:%20BlockAttributes)
+- [BlockDefinition](../wiki/Interface:%20BlockDefinition)
+- [BlockElement](../wiki/Interface:%20BlockElement)
+- [ColorTheme](../wiki/Interface:%20ColorTheme)
+- [ExternalBlockDefinition](../wiki/Interface:%20ExternalBlockDefinition)
+- [SBColors](../wiki/Interface:%20SBColors)
+- [SBFileType](../wiki/Interface:%20SBFileType)
+- [SBImageEntity](../wiki/Interface:%20SBImageEntity)
+- [SBUserAvatar](../wiki/Interface:%20SBUserAvatar)
+- [SBUserProfile](../wiki/Interface:%20SBUserProfile)
+- [UserListItem](../wiki/Interface:%20UserListItem)
+- [UserListRequestQuery](../wiki/Interface:%20UserListRequestQuery)
+- [UserListResponse](../wiki/Interface:%20UserListResponse)
+- [WidgetApi](../wiki/Interface:%20WidgetApi)

package/lib/base-block.ts

@@ -1,5 +1,5 @@
 /*!
- * Copyright 2020, Staffbase GmbH and contributors.
+ * Copyright 2021, Staffbase GmbH and contributors.
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
@@ -11,6 +11,13 @@
  * limitations under the License.
  */
 
+type Value = string | number | boolean | unknown[] | Record<string, unknown> | null | undefined;
+
+/**
+ * Generic map of parsed attributes.
+ */
+type ValueMap = Record<string, Value>;
+
 /**
  * Base class for custom widgets.
  *
@@ -79,7 +86,7 @@ export interface BaseBlock extends HTMLElement {
    * NOTE: The default implementation turns every value in a string, except arrays and object, which
    * are converted to base64 encoded data uris in the format `data:text/plain;base64,...`
    */
-  parseConfig<T extends Record<string, any>>(attributes: T): Record<string, string>;
+  parseConfig<T extends ValueMap>(attributes: T): Record<string, string>;
 
   /**
    * Called when the config dialog is opened. The dialog uses the parsed attributes, to fill
@@ -95,7 +102,7 @@ export interface BaseBlock extends HTMLElement {
    * NOTE: The default implementation converts every string to string, boolean or number and decodes
    * and parses the data uris to the arrays and objects. Dates are remaining a string!
    */
-  parseAttributes<T extends Record<string, any>>(): T;
+  parseAttributes(): ValueMap;
 
   /**
    * The content language as defined in the hosting system. Should be used to provide

package/lib/block-attributes.ts

@@ -1,5 +1,5 @@
 /*!
- * Copyright 2020, Staffbase GmbH and contributors.
+ * Copyright 2021, Staffbase GmbH and contributors.
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at

package/lib/block-definition.ts

@@ -1,5 +1,5 @@
 /*!
- * Copyright 2020, Staffbase GmbH and contributors.
+ * Copyright 2021, Staffbase GmbH and contributors.
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
@@ -17,39 +17,73 @@ import {UiSchema} from '@rjsf/core';
 
 export interface BlockDefinition<Factory = BlockFactory> {
   /**
-   * tag of the widget, must be compatible with webcomponent naming conventions
+   * The tag name of the widget. It must be compatible with 
+   * webcomponent naming conventions.
+   *
+   * @see https://www.webcomponents.org/community/articles/how-should-i-name-my-element
    */
   name: string;
 
   /**
-   * the implementation of the webcomponent
+   * The implementation of the web component.
    */
   factory: Factory;
 
   /**
-   * can be used for extending from a built-in element
+   * Can be used for extending from a built-in element.
    */
   options?: ElementDefinitionOptions;
 
   /**
-   * DOM-attributes of the element, must be kebab-case
+   * DOM attributes of the element, must be in kebab-case.
    */
   attributes: string[];
 
   /**
-   * set to "inline" if you want the element to behave like a span element rather than a div element
-   * if not specified, it defaults to "block"
+   * Set to `inline` if you want the element to behave like a span element
+   * rather than a div element if not specified, it defaults to `block`.
    */
   blockLevel?: "block" | "inline";
 
   /**
-   * schema used for creating the configuration form
+   * Schema used for defining the configuration form.
+   *
+   * @example
+   * ```json
+   * {
+   *  "type": "object",
+   *  "required": [
+   *    "firstName",
+   *    "lastName"
+   *    ],
+   *  "properties": {
+   *    "firstName": {
+   *      "type": "string",
+   *      "title": "First name"
+   *      },
+   *  "lastName": {
+   *    "type": "string",
+   *    "title": "Last name"
+   *    }
+   *  }
+   * }
+   * ```
    * @see https://react-jsonschema-form.readthedocs.io/en/latest/
    */
   configurationSchema: JSONSchema7;
   
   /**
-   * schema to add more customization to the form's look and feel
+   *
+   * Schema to add more customization to the look and feel of the configuration form.
+   *
+   * ```json
+   * {
+   *   "firstName": {
+   *      "ui:help": "Your first name."
+   *   }
+   * }
+   * ```
+   *
    * @see https://react-jsonschema-form.readthedocs.io/en/latest/api-reference/uiSchema/
    */
   uiSchema?: UiSchema;

package/lib/block-element.ts

@@ -1,5 +1,5 @@
 /*!
- * Copyright 2020, Staffbase GmbH and contributors.
+ * Copyright 2021, Staffbase GmbH and contributors.
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at
@@ -18,12 +18,12 @@ export interface BlockElement {
   // readonly observedAttributes: string[];
 
   /**
-   * Invoked when the custom element is first connected to the document's DOM.
+   * Invoked when the custom element is first connected to the DOM.
    */
   connectedCallback: () => void;
 
   /**
-   * Invoked when the custom element is disconnected from the document's DOM.
+   * Invoked when the custom element is disconnected from the DOM.
    */
   disconnectedCallback: () => void;
 
@@ -33,13 +33,13 @@ export interface BlockElement {
   adoptedCallback: () => void;
 
   /**
-   * Invoked when one of the custom element's attributes is added, removed, or changed.
+   * Invoked when one of the attributes of the custom element is added, removed, or changed.
    *
    * Note that you have to statically register the observed values with the 'observedAttributes' static getter.
    *
    * @param attrName The changed attributes name
-   * @param oldValue
-   * @param newValue
+   * @param oldValue The old value
+   * @param newValue The new value
    */
   attributeChangedCallback: (
     attrName: string,

package/lib/block-factory.ts

@@ -1,5 +1,5 @@
 /*!
- * Copyright 2020, Staffbase GmbH and contributors.
+ * Copyright 2021, Staffbase GmbH and contributors.
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at

package/lib/external-block-definition.ts

@@ -1,5 +1,5 @@
 /*!
- * Copyright 2020, Staffbase GmbH and contributors.
+ * Copyright 2021, Staffbase GmbH and contributors.
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at

package/lib/global.d.ts

@@ -1,5 +1,5 @@
 /*!
- * Copyright 2020, Staffbase GmbH and contributors.
+ * Copyright 2021, Staffbase GmbH and contributors.
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
  * You may obtain a copy of the License at

package/lib/widget-api-types.ts

@@ -96,7 +96,8 @@ export interface SBColors {
 }
 
 /**
- * Color theme entity definition
+ * The color theme allows the widget to mimic the look
+ * and feel of the Staffbase ecosystem it was added to.
  */
 export interface ColorTheme {
     bgColor: string;
@@ -146,7 +147,8 @@ export interface SBUserProfile {
 }
 
 /**
- * sorting order 
+ * The sorting order of the user list.
+ *
  * @param lastname sort response by lastName_ASC_firstName_ASC (default)
  * @param created sort by date of creation descending
  * @param updated sort by date of last update descending
@@ -182,3 +184,17 @@ export interface UserListResponse {
     limit: number;
     total: number;
 }
+
+
+export type IntegrationType = "ms365"
+
+/**
+ * Integration Token including the expiration time
+ */
+export interface IntegrationToken {
+    // the token to access the api of the integration
+    accessToken: string;
+
+    // date when the access token expires
+    accessTokenExpiresAt?: Date;
+}

package/lib/widget-api.ts

@@ -11,25 +11,25 @@
  * limitations under the License.
  */
 
-import { ColorTheme, SBUserProfile, UserListRequestQuery, UserListResponse } from './widget-api-types';
+import { ColorTheme, IntegrationToken, IntegrationType, SBUserProfile, UserListRequestQuery, UserListResponse } from './widget-api-types';
 
 
 /**
- * WidgetApi class.
+ * Widget API class.
  *
- * A class providing access to additional information for widgets
+ * A class providing access to additional information about the Staffbase ecosystem for widgets.
  */
 export interface WidgetApi {
     /**
-     * Call to retrieve the color theme of the app. Since this themes definitions
+     * Call to retrieve the color theme of the app. Since this theme definitions
      * are currently redesigned, this method is called legacy.
      *
-     * @returns A promise containing the SBUserProfile or an error is returned
+     * @returns An object containing the color theme data is returned.
      */
     getLegacyAppTheme(): ColorTheme;
 
     /**
-     * Call to retrieve the user profile of the current or a specific user
+     * Call to retrieve the user profile of the current or a specific user.
      *
      * @param userId User ID to lookup for; leave blank to retrieve current user
      * @returns A promise containing the SBUserProfile is returned. In case of an error,
@@ -38,7 +38,7 @@ export interface WidgetApi {
     getUserInformation(userId?: string): Promise<SBUserProfile>;
 
     /**
-     * Call to retrieve the user profile by its external ID
+     * Call to retrieve a user profile by its external ID.
      *
      * @param externalId An external ID of the user that shall be returned
      * @returns A promise containing the SBUserProfile is returned. In case of an error,
@@ -47,7 +47,7 @@ export interface WidgetApi {
     getUserInformationByExternalId(externalId: string): Promise<SBUserProfile>;
 
     /**
-     * Call to retrieve a list of users determined by the query object
+     * Call to retrieve a list of users determined by the query object.
      *
      * @param query Adjust limit, offset, filter, and sorting for the request
      * @returns A promise containing the UserListResponse is returned. In case of an error,
@@ -55,4 +55,14 @@ export interface WidgetApi {
      */
     getUserList(query: UserListRequestQuery): Promise<UserListResponse>;
 
+
+    /**
+     * Call to retrieve a valid token to access the Microsoft API. Includes a time value to
+     * refresh the token.
+     *
+     * @param type The name of the integration. ("ms365")
+     * @returns A promise containing the IntegrationToken is returned. In case of an error,
+     * the promise is rejected.
+     */
+    getIntegration(type: IntegrationType): Promise<IntegrationToken | null>;
 }

package/package.json

@@ -1,27 +1,33 @@
 {
   "name": "@staffbase/widget-sdk",
-  "version": "3.3.1",
-  "description": "sdk for widgets",
+  "version": "3.4.0-beta.1",
+  "description": "Staffbase SDK for Custom Widgets",
   "keywords": [
     "web-components"
   ],
-  "license": "Apache-2.0",
-  "author": "Staffbase",
   "scripts": {
+    "clean-doc": "npx rimraf docs",
+    "doc": "npm run clean-doc && typedoc --out docs index.d.ts --plugin typedoc-plugin-markdown --readme none --disableSources --theme ./node_modules/typedoc-github-wiki-theme/dist",
     "release": "semantic-release",
     "prepare": "husky install"
   },
+  "license": "Apache-2.0",
+  "author": "Staffbase",
   "dependencies": {
-    "@rjsf/core": "2.5.0",
+    "@rjsf/core": "3.0.0",
     "@types/json-schema": "^7.0.5"
   },
   "devDependencies": {
-    "@amanda-mitchell/semantic-release-npm-multiple": "2.8.0",
-    "@commitlint/cli": "12.1.1",
-    "@commitlint/config-conventional": "12.1.1",
-    "@tmware/semantic-release-npm-github-publish": "1.4.3",
-    "husky": "^6.0.0",
+    "@amanda-mitchell/semantic-release-npm-multiple": "2.12.0",
+    "@commitlint/cli": "13.1.0",
+    "@commitlint/config-conventional": "13.1.0",
+    "@tmware/semantic-release-npm-github-publish": "1.4.4",
+    "@types/react": "^17.0.15",
+    "husky": "^7.0.1",
     "semantic-release": "^17.4.2",
+    "typedoc": "0.21.5",
+    "typedoc-github-wiki-theme": "0.5.1",
+    "typedoc-plugin-markdown": "3.10.4",
     "typescript": "^4.2.4"
   },
   "repository": {

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "commonjs",
+    "noEmit": true,
+
+    "strict": true,
+
+    "moduleResolution": "node",
+    "baseUrl": "./",
+    "esModuleInterop": true
+  }
+}