feat: migrate record-user-acknowledgements

Co-authored-by: dackers86 <[email protected]>

Author: Ehesp

.prettierignore

@@ -3,3 +3,4 @@ build
 **/functions/lib/**/*.js
 **/extensions/image-processing-api/lib/src/types/**/*.ts
 package-lock.json
+**/public/build/**

dictionary.js

@@ -59,4 +59,7 @@ module.exports = [
   /^firebase/,
   /^href/,
   /^stringified/,
+  /^acknowledgement/,
+  /^acknowledgements/,
+  /^unacknowledge/,
 ];

docs.json

@@ -14,6 +14,13 @@
         ["Types", "/image-processing-api/types"],
         ["Utility Library", "/image-processing-api/utility-library"]
       ]
+    ],
+    [
+      "Record User Acknowledgements",
+      [
+        ["Overview", "/record-user-acknowledgements"],
+        ["Refernce API", "/record-user-acknowledgements/reference"]
+      ]
     ]
   ]
 }

docs/index.mdx

@@ -6,6 +6,7 @@
   <h2 align="center">Invertase Firebase Extensions</h2>
 </p>
 
-| Name                                          |                           Description                           |
-| --------------------------------------------- | :-------------------------------------------------------------: |
-| [Image Processing Api](/image-processing-api) | Firebase deployed function for processing and rendering images. |
+| Name                                                          |                                  Description                                   |
+| ------------------------------------------------------------- | :----------------------------------------------------------------------------: |
+| [Image Processing Api](/image-processing-api)                 |        Firebase deployed function for processing and rendering images.         |
+| [Record User Acknowledgements](/record-user-acknowledgements) | Provides an out of the box acknowledgement management extension for Firestore. |

docs/record-user-acknowledgements/assets/admin-dashboard-example.png

@@ -0,0 +1,118 @@
+# Record User Acknowledgements
+
+The extension stores notices and acknowledgements as documents in a collection inside Firestore. You configure the collection during the installation process, when you set up the extension instance's configuration parameters.
+
+The extensions' source code contains a [web app providing admin utilities](https://github.com/invertase/firebase-extensions/tree/main/extensions/firestore-record-user-acknowledgements/admin-dashboard) that you can run locally. This contains a notice builder UI that you can use to easily create and customize notices. Setup instructions are available in the above link provided. Once set up, navigate to [localhost:3000](http://localhost:3000) to see the notice builder tool.
+
+![Admin Dashboard](/record-user-acknowldegements/assets/admin-dashboard-example.png)
+
+## Retrieving a notice
+
+After creating a notice, you can use the following snippet in your web/mobile app to get the notice you want to show to your users, using the notice `type`:
+
+```js
+import { getFunctions, httpsCallable } from 'firebase/functions';
+
+const functions = getFunctions();
+const notice = await httpsCallable(
+  functions,
+  'ext-firestore-record-user-acknowledgements-getNotice',
+)({
+  type: 'banner',
+});
+```
+
+Note: if multiple instances of this extension are installed the callable function name might contain a unique identifier, e.g. `ext-firestore-record-user-acknowledgements-<id>-getNotice`.
+
+The response of the function call will contain the notice document data, along with whether the current authenticated user has acknowledged the notice.
+
+To retrieve a notice by a specific version, provide the `version` parameter:
+
+```js
+import { getFunctions, httpsCallable } from 'firebase/functions';
+
+const functions = getFunctions();
+const notice = await httpsCallable(
+  functions,
+  'ext-firestore-record-user-acknowledgements-getNotice',
+)({
+  type: 'banner',
+  version: 2,
+});
+```
+
+View the [reference API](/record-user-acknowldegements/reference) for full details on the response interface.
+
+## Acknowledging a notice
+
+To acknowledge a notice, the extension provides two callable functions which accept the notice ID: `acknowledgeNotice` & `unacknowledgeNotice`. The extension will keep historical records of each acknowledgement the callable functions are called multiple times for the same user and notice.
+
+For example, to acknowledge a notice:
+
+```js
+import { getFunctions, httpsCallable } from "firebase/functions";
+
+const functions = getFunctions();
+await httpsCallable(functions, 'ext-firestore-record-user-acknowledgements-acknowledgeNotice)({
+  noticeId: 'EA9QhZKKta9KXcckiasc',
+});
+```
+
+In-case you need to capture custom preferences relating to an acknowledgement, you can provide custom metadata to the function, for example:
+
+```js
+await httpsCallable(functions, 'ext-firestore-record-user-acknowledgements-acknowledgeNotice)({
+  noticeId: 'EA9QhZKKta9KXcckiasc',
+  metadata: { preference1: true, preference2: false },
+});
+```
+
+You can also provide a custom “type” of acknowledgement (the default type is “seen”), for example:
+
+```js
+await httpsCallable(functions, 'ext-firestore-record-user-acknowledgements-acknowledgeNotice)({
+  noticeId: 'EA9QhZKKta9KXcckiasc',
+  type: 'seen',
+});
+```
+
+If you wish to unacknowledge a notice, call the `unacknowledgeNotice` function:
+
+```js
+await httpsCallable(functions, 'ext-firestore-record-user-acknowledgements-unacknowledgeNotice)({
+  noticeId: 'EA9QhZKKta9KXcckiasc',
+  metadata: { reason: '...' },
+});
+```
+
+## Retrieving acknowledgements
+
+To retrieve all previous user notice acknowledgements, call the `getAcknowledgements` callable function. This function will return an ordered array of all acknowledgements along with the notice data:
+
+```js
+import { getFunctions, httpsCallable } from "firebase/functions";
+
+const functions = getFunctions();
+const acknowledgements  = await httpsCallable(functions, 'ext-firestore-record-user-acknowledgements-getAcknowledgements)();
+```
+
+By default this won’t include unacknowledgement documents, however if those are required you can provide a `includeUnacknowledgements` property to the call:
+
+```js
+import { getFunctions, httpsCallable } from "firebase/functions";
+
+const functions = getFunctions();
+const acknowledgements  = await httpsCallable(functions, 'ext-firestore-record-user-acknowledgements-getAcknowledgements)({
+  includeUnacknowledgements: true,
+});
+```
+
+## User specific acknowledgements
+
+You may need to create custom notices that are shown to and can only be acknowledged by a specific subset of users. To accomplish this, specify an `allowList` array of UIDs to the notice document. If the user requesting a notice by type is not within the list of UIDs, a `not-found` error will be returned.
+
+## Updating a notice
+
+When it's time to update a notice, for example when additional user preferences are required, create a new notice document with the same `type` as the existing notice you wish to update.
+
+When the notice is retrieved, a new notice document will be returned with no user acknowledgement, allowing users to acknowledge the newer notice.

docs/record-user-acknowledgements/index.mdx

@@ -0,0 +1,136 @@
+# API Reference
+
+Below contains an overview of the specifications for the Record User Acknowledgements extension, including TypeScript definitions & detailed descriptions.
+
+## `NoticeDocument` Interface
+
+The specification for a single document within the configured collection:
+
+```ts
+export interface NoticeDocument {
+  // The document ID.
+  id: string;
+  // The type of notice, e.g. `banner` | `terms-and-condition` | `privacy-policy`.
+  type: string;
+  // An optional notice version. This can be used to filter a specific notice versions via the `getNotice` callable function.
+  version?: number;
+  // The optional title of the notice.
+  title?: string;
+  // The optional description of the notice.
+  description?: string;
+  // The optional link of the notice.
+  link?: string;
+  // The timestamp when the notice was created.
+  createdAt: Timestamp;
+  // A list of user IDs that are allowed to see the notice.
+  allowList: string[];
+}
+```
+
+## `AcknowledgementDocument` Interface
+
+The specification for a single document within a notice sub-collection:
+
+```ts
+type BaseAcknowledgement = {
+  // The document ID.
+  id: string;
+  // The UID of the user who acknowledged the notice.
+  userId: string;
+  // The ID of the notice that was acknowledged.
+  noticeId: string;
+  // The timestamp when the notice was acknowledged.
+  createdAt: Timestamp;
+  // The optional metadata of the acknowledgement.
+  metadata: any;
+};
+
+export type AcknowledgementDocument =
+  | (BaseAcknowledgement & {
+      // The type of the acknowledgement.
+      ackEvent: 'acknowledged';
+      // The type of the acknowledgement. Defaults to `seen`.
+      type: string;
+    })
+  | (BaseAcknowledgement & {
+      // The type of the acknowledgement.
+      ackEvent: 'unacknowledged';
+    });
+```
+
+## `GetNoticeRequest` Interface
+
+The response interface provided to a `getNotice` callable function:
+
+```ts
+export interface GetNoticeRequest {
+  // The `type` of the notice to get.
+  type: string;
+  // If provided, the specific version of this notice (if exists) will be returned.
+  version?: number;
+}
+```
+
+## `GetNoticeResponse` Interface
+
+The result interface returned from a `getNotice` callable function:
+
+```ts
+export type GetNoticeResponse = Omit<NoticeDocument, ‘allowList’> & {
+ // The timestamp when the notice was unacknowledged by the user (undefined if the user has not unacknowledged this notice).
+ unacknowledgedAt?: Timestamp;
+
+ // An ordered array of user acknowledgements.
+ acknowledgements: AcknowledgementDocument[];
+}
+```
+
+## `AcknowledgeNoticeRequest` Interface
+
+The response interface provided to a `acknowledgeNotice` callable function:
+
+```ts
+export interface AcknowledgeNoticeRequest {
+  // The notice ID to acknowledge.
+  noticeId: string;
+  // A custom type to provide as the acknowledgement. Defaults to `seen`.
+  type?: string;
+  // Optional preference metadata to store with this acknowledgement.
+  metadata?: any;
+}
+```
+
+## `UnacknowledgeNoticeRequest` Interface
+
+The response interface provided to a `unacknowledgeNotice` callable function:
+
+```ts
+export interface UnacknowledgeNoticeRequest {
+  // The notice ID to unacknowledge.
+  noticeId: string;
+  // Optional preference metadata to store with this unacknowledgement.
+  metadata?: any;
+}
+```
+
+## `GetAcknowledgementsRequest` Interface
+
+The response interface provided to a `getAcknowledgements` callable function:
+
+```ts
+export interface GetAcknowledgementsRequest {
+  // If true, include unacknowledgement documents.
+  includeUnacknowledgements?: boolean;
+}
+```
+
+## `GetAcknowledgementsResponse` Interface
+
+The response interface provided to a `getAcknowledgements` callable function:
+
+```ts
+export type GetAcknowledgementsResponse  = (AcknowledgementDocument & {
+  // The notice of this acknowledgement, excluding the allowList.
+  notice: Omit<NoticeDocument, ‘allowList’>;
+})[];
+```

docs/record-user-acknowledgements/reference.mdx

@@ -0,0 +1,3 @@
+## Version 0.1.0
+
+Stable release with documentation.