feat: add support for created by and last edited by

Author: alvis

source/client.ts

@@ -13,7 +13,7 @@
  * -------------------------------------------------------------------------
  */
 
-import { Client } from '@notionhq/client';
+import { APIErrorCode, Client, isNotionClientError } from '@notionhq/client';
 import { caching } from 'cache-manager';
 import { dump } from 'js-yaml';
 
@@ -27,18 +27,19 @@ import {
   normalizeProperties,
 } from '#property';
 
+import type { Cache } from 'cache-manager';
+
 import type {
   Block,
   Database,
   NotionAPIDatabase,
   NotionAPIList,
   NotionAPIPage,
   NotionAPITitle,
+  NotionAPIUser,
   Page,
 } from './types';
 
-import type { Cache } from 'cache-manager';
-
 export interface NotionTTL {
   /** the number of seconds in which a database metadata will be cached */
   databaseMeta: number;
@@ -142,7 +143,13 @@ export class Notion {
       object: 'database',
       parent: database.parent,
       title: getPropertyContentFromRichText(database.title),
-      metadata: getMetadata(database),
+      metadata: getMetadata({
+        ...database,
+        /* eslint-disable @typescript-eslint/naming-convention */
+        created_by: await this.getUser(database.created_by.id),
+        last_edited_by: await this.getUser(database.last_edited_by.id),
+        /* eslint-enable @typescript-eslint/naming-convention */
+      }),
       pages: normalizedPages,
     };
   }
@@ -168,6 +175,32 @@ export class Notion {
     return this.normalizePageAndCache(page);
   }
 
+  /**
+   * get user detail with cache
+   * @param id the uuid of a Notion user to be queried
+   * @returns user object returned from Notion's API
+   */
+  public async getUser(id: string): Promise<NotionAPIUser | null> {
+    try {
+      return await this.cache.wrap(
+        `user:${id}`,
+        /* eslint-disable @typescript-eslint/naming-convention */
+        async () => this.client.users.retrieve({ user_id: id }),
+        /* eslint-enable @typescript-eslint/naming-convention */
+      );
+    } catch (error) {
+      if (
+        isNotionClientError(error) &&
+        error.code === APIErrorCode.RestrictedResource
+      ) {
+        // NOTE: not throwing an error here because users may still want other data
+        return null;
+      } else {
+        throw error;
+      }
+    }
+  }
+
   /**
    * get all block related to a collection
    * @param id the uuid of the collection, either a database or page or a parent block
@@ -193,7 +226,7 @@ export class Notion {
           ...(block.has_children
             ? { has_children: true, children: await this.getBlocks(block.id) }
             : { has_children: false }),
-          /* eslint-enable */
+          /* eslint-enable @typescript-eslint/naming-convention */
         }),
       ),
     );
@@ -213,7 +246,13 @@ export class Notion {
     )[0];
     const title = getPropertyContentFromRichText(titleProperty.title);
 
-    const metadata = getMetadata(page);
+    const metadata = getMetadata({
+      ...page,
+      /* eslint-disable @typescript-eslint/naming-convention */
+      created_by: await this.getUser(page.created_by.id),
+      last_edited_by: await this.getUser(page.last_edited_by.id),
+      /* eslint-enable @typescript-eslint/naming-convention */
+    });
 
     return {
       id: page.id,

source/metadata.ts

@@ -13,35 +13,74 @@
  * -------------------------------------------------------------------------
  */
 
-import { getPropertyContentFromFile } from '#property';
+import {
+  getPropertyContentFromFile,
+  getPropertyContentFromUser,
+} from '#property';
 
-import type { Metadata, NotionAPIDatabase, NotionAPIPage } from '#types';
+import type {
+  EntityWithUserDetail,
+  Metadata,
+  NotionAPIDatabase,
+  NotionAPIPage,
+  NotionAPIUser,
+} from '#types';
 
 /**
  * get common properties from a page or database, except for the title
  * @param entity the page or database object returned from Notion API
  * @returns common properties
  */
-export function getMetadata<E extends NotionAPIPage | NotionAPIDatabase>(
-  entity: E,
-): Metadata {
+export function getMetadata<
+  E extends EntityWithUserDetail<NotionAPIPage | NotionAPIDatabase>,
+>(entity: E): Metadata {
   const { last_edited_time: lastEditedTime, url } = entity;
   const { created_time: createdTime } = entity;
 
-  const variable = { url, lastEditedTime };
-  const invariant = { createdTime };
+  const variable = {
+    url,
+    ...getCommonPersonMetadata('lastEditedBy', entity.last_edited_by),
+    lastEditedTime,
+  };
+  const invariant = {
+    ...getCommonPersonMetadata('createdBy', entity.created_by),
+    createdTime,
+  };
   const visual = getCommonVisualMetadata(entity);
 
   return { ...variable, ...invariant, ...visual };
 }
 
+/**
+ * get common visual properties from a page or database
+ * @param prefix the prefix attached to the property name
+ * @param user the user object returned from Notion API
+ * @returns common properties
+ */
+export function getCommonPersonMetadata<P extends string>(
+  prefix: P,
+  user: NotionAPIUser | null,
+): {
+  [K in `${P}${'Avatar' | 'Email' | 'Name'}`]: string | null;
+} {
+  const properties = getPropertyContentFromUser(user);
+
+  return {
+    [`${prefix}Avatar`]: properties?.avatar ?? null,
+    [`${prefix}Email`]: properties?.email ?? null,
+    [`${prefix}Name`]: properties?.name ?? null,
+  } as {
+    [K in `${P}${'Avatar' | 'Email' | 'Name'}`]: string | null;
+  };
+}
+
 /**
  * get common visual properties such as cover and icon from a page or database
  * @param entity the page or database object returned from Notion API
  * @returns common properties
  */
 export function getCommonVisualMetadata<
-  E extends NotionAPIPage | NotionAPIDatabase,
+  E extends EntityWithUserDetail<NotionAPIPage | NotionAPIDatabase>,
 >(
   entity: E,
 ): {

source/property.ts

@@ -53,7 +53,9 @@ export function getPropertyContent<
   formula: boolean | number | string | null;
   rollup: number | string | null;
   created_time: string;
+  created_by: Person | null;
   last_edited_time: string;
+  last_edited_by: Person | null;
   /* eslint-enable @typescript-eslint/naming-convention */
 }[T];
 export function getPropertyContent(
@@ -94,8 +96,12 @@ export function getPropertyContent(
       return getPropertyContentFromFormula(property.formula);
     case 'rollup':
       return getPropertyContentFromRollup(property.rollup);
+    case 'created_by':
+      return getPropertyContentFromUser(property.created_by);
     case 'created_time':
       return property.created_time;
+    case 'last_edited_by':
+      return getPropertyContentFromUser(property.last_edited_by);
     case 'last_edited_time':
       return property.last_edited_time;
     // @ts-expect-error Notion has unsupported property type in the past and also maybe in future

source/types/index.d.ts

@@ -83,7 +83,13 @@ export type Block = NotionAPIBlock &
 
 export type Metadata = {
   url: string;
+  createdByAvatar: string | null;
+  createdByEmail: string | null;
+  createdByName: string | null;
   createdTime: string;
+  lastEditedByAvatar: string | null;
+  lastEditedByEmail: string | null;
+  lastEditedByName: string | null;
   lastEditedTime: string;
   coverImage: string | null;
   iconEmoji: string | null;

spec/client.spec.ts

@@ -15,9 +15,10 @@
 
 import assert from 'assert';
 
-import { Notion, getCommonMetadata } from '#client';
-import { mockDatabase, mockPage } from './mock';
-import { NotionAPIPage } from '#types';
+import { APIErrorCode } from '@notionhq/client';
+
+import { Notion } from '#client';
+import { mockDatabase, mockPage, mockUser } from './mock';
 
 describe('cl:Notion', () => {
   const client = new Notion({ token: 'token' });
@@ -70,7 +71,13 @@ describe('cl:Notion', () => {
 ---
 title: 'Text'
 url: 'https://www.notion.so/workspace/page'
+lastEditedByAvatar: 'url'
+lastEditedByEmail: 'email'
+lastEditedByName: 'Name'
 lastEditedTime: '2020-01-01T00:00:00Z'
+createdByAvatar: 'url'
+createdByEmail: 'email'
+createdByName: 'Name'
 createdTime: '2020-01-01T00:00:00Z'
 coverImage: 'https://www.notion.so/cover.png'
 iconEmoji: '📚'
@@ -97,4 +104,61 @@ page-block1-block0
       expect(page.blocks.length).toEqual(BLOCKS_PER_PAGE);
     });
   });
+
+  describe('fn:getUser', () => {
+    it('return user information as detail as possible', async () => {
+      const userID = 'user_with_full_detail';
+      mockUser({ userID });
+
+      const user = await client.getUser(userID);
+
+      expect(user).toEqual({
+        object: 'user',
+        type: 'person',
+        id: userID,
+        name: 'Name',
+        avatar_url: 'url',
+        person: {
+          email: 'email',
+        },
+      });
+    });
+
+    it('return null for API token without user read capability', async () => {
+      const userID = 'inaccessible_user';
+      mockUser(
+        { userID },
+        {
+          error: {
+            type: 'code',
+            status: 403,
+            code: APIErrorCode.RestrictedResource,
+          },
+        },
+      );
+
+      const user = await client.getUser(userID);
+
+      expect(user).toEqual(null);
+    });
+
+    it('throw an error if there is any unexpected http error other than 403', async () => {
+      const userID = 'http_error';
+      mockUser(
+        { userID },
+        {
+          error: { type: 'code', status: 400, code: APIErrorCode.InvalidJSON },
+        },
+      );
+
+      await expect(async () => client.getUser(userID)).rejects.toThrowError();
+    });
+
+    it('throw any non http error', async () => {
+      const userID = 'network_error';
+      mockUser({ userID }, { error: { type: 'network' } });
+
+      await expect(async () => client.getUser(userID)).rejects.toThrowError();
+    });
+  });
 });