@verdocs/js-sdk 1.0.8 → 1.0.12

package/src/Users/Auth.ts

@@ -0,0 +1,114 @@
+import {getEndpoint} from '../HTTP/Transport';
+import {
+  IAuthenticateAppRequest,
+  IAuthenticateResponse,
+  IAuthenticateUserRequest,
+  TokenValidationRequest,
+  TokenValidationResponse,
+  UpdateEmailRequest,
+  UpdateEmailResponse,
+  UpdatePasswordRequest,
+  UpdatePasswordResponse,
+} from './Types';
+
+/**
+ * Authenticate to Verdocs via user/password authentication
+ *
+ * ```typescript
+ * import {Auth} from '@verdocs/js-sdk/Auth';
+ * import {Transport} from '@verdocs/js-sdk/HTTP';
+ *
+ * const {accessToken} = await Auth.authenticateUser({ username: 'test@test.com', password: 'PASSWORD' });
+ * Transport.setAuthToken(accessToken);
+ * ```
+ */
+export const authenticateUser = (params: IAuthenticateUserRequest) =>
+  getEndpoint()
+    .post<IAuthenticateResponse>('/authentication/login', params)
+    .then((r) => r.data);
+
+/**
+ * Authenticate to Verdocs via client ID / Secret authentication. **NOTE: This is only suitable for
+ * NodeJS server-side applications. Never expose your Client Secret in a Web or Mobile app!** Also note
+ * that access tokens may be cached by server-side apps (and this is recommended) but do expire after 2
+ * hours. This expiration may change based on future security needs. Application developers are encouraged
+ * to check the `exp` expiration field in the response accessToken and renew tokens after they expire.
+ *
+ * ```typescript
+ * import {Auth} from '@verdocs/js-sdk/Auth';
+ * import {Transport} from '@verdocs/js-sdk/HTTP';
+ *
+ * const {accessToken} = await Auth.authenticateApp({ client_id: 'CLIENTID', client_secret: 'SECRET' });
+ * Transport.setAuthToken(accessToken);
+ * ```
+ */
+export const authenticateApp = (params: IAuthenticateAppRequest): Promise<IAuthenticateResponse> =>
+  getEndpoint()
+    .post('/authentication/login_client', {}, {headers: params})
+    .then((r) => r.data);
+
+/**
+ * Validate a token. Only Verdocs tokens will be accepted. Most applications can decode tokens locally,
+ * because tokens will be validated when API calls are made anyway. However, high-security applications
+ * may use this endpoint to check if a token has been revoked.
+ *
+ * ```typescript
+ * import {Auth} from '@verdocs/js-sdk/Auth';
+ *
+ * const {valid} = await Auth.validateToken({ token });
+ * if (!valid) {
+ *   window.alert('Session invalid or expired. Please re-authenticate.');
+ * }
+ * ```
+ */
+export const validateToken = (params: TokenValidationRequest): Promise<TokenValidationResponse> =>
+  getEndpoint()
+    .post('/token/isValid', params)
+    .then((r) => r.data);
+
+/**
+ * If called before the session expires, this will refresh the caller's session and tokens.
+ *
+ * ```typescript
+ * import {Auth} from '@verdocs/js-sdk/Auth';
+ * import {Transport} from '@verdocs/js-sdk/HTTP';
+ *
+ * const {accessToken} = await Auth.refreshTokens();
+ * Transport.setAuthToken(accessToken);
+ * ```
+ */
+export const refreshTokens = (): Promise<IAuthenticateResponse> =>
+  getEndpoint()
+    .get('/token')
+    .then((r) => r.data);
+
+/**
+ * Update the caller's password. To help prevent CSRF attack vectors, the user's old password and email address are required.
+ *
+ * ```typescript
+ * import {Auth} from '@verdocs/js-sdk/Auth';
+ *
+ * const {status, message} = await Auth.updatePassword({ email, oldPassword, newPassword });
+ * if (status !== 'OK') {
+ *   window.alert(`Password reset error: ${message}`);
+ * }
+ * ```
+ */
+export const updatePassword = (params: UpdatePasswordRequest): Promise<UpdatePasswordResponse> =>
+  getEndpoint()
+    .put('/user/update_password', params)
+    .then((r) => r.data);
+
+/**
+ * Update the caller's email address.
+ *
+ * ```typescript
+ * import {Auth} from '@verdocs/js-sdk/Auth';
+ *
+ * const {profiles} = await Auth.updateEmail({ email: newEmail });
+ * ```
+ */
+export const updateEmail = (params: UpdateEmailRequest): Promise<UpdateEmailResponse> =>
+  getEndpoint()
+    .put('/user/update_email', params)
+    .then((r) => r.data);

package/src/Users/Billing.ts

@@ -0,0 +1,3 @@
+import {getEndpoint} from '../HTTP/Transport';
+
+// TODO

package/src/Users/Notifications.ts

@@ -0,0 +1,6 @@
+import {getEndpoint} from '../HTTP/Transport';
+
+export const getNotifications = async () =>
+  getEndpoint()
+    .get('/notifications')
+    .then((r) => r.data);

package/src/Users/Profiles.ts

@@ -0,0 +1,153 @@
+import {getEndpoint} from '../HTTP/Transport';
+import {
+  ICreateProfileRequest,
+  IPermission,
+  IProfile,
+  IRole,
+  ISwitchProfileResponse,
+  IUpdateProfileRequest,
+} from './Types';
+import {IGroup} from '../Organizations/Types';
+
+/**
+ * Get the user's available profiles. The current profile will be marked with `current: true`.
+ *
+ * ```typescript
+ * import {Profiles} from '@verdocs/js-sdk/Users';
+ *
+ * const profiles = await Profiles.getProfiles()
+ * ```
+ */
+export const getProfiles = () =>
+  getEndpoint()
+    .get<IProfile[]>('/profiles')
+    .then((r) => r.data);
+
+/**
+ * Get a list of system roles.
+ *
+ * ```typescript
+ * import {Profiles} from '@verdocs/js-sdk/Users';
+ *
+ * const roles = await Profiles.getRoles();
+ * ```
+ */
+export const getRoles = () =>
+  getEndpoint()
+    .get<IRole[]>('/roles')
+    .then((r) => r.data);
+
+/**
+ * Get a list of system roles.
+ *
+ * ```typescript
+ * import {Profiles} from '@verdocs/js-sdk/Users';
+ *
+ * const permissions = await Profiles.getPermissions();
+ * ```
+ */
+export const getPermissions = () =>
+  getEndpoint()
+    .get<IPermission[]>('/permissions')
+    .then((r) => r.data);
+
+/**
+ * Create a profile. If the caller does not have a "current" profile set, the new profile will be made current.
+ *
+ * ```typescript
+ * import {Profiles} from '@verdocs/js-sdk/Users';
+ *
+ * const newProfile = await Profiles.createProfile({ first_name: 'FIRST', last_name: 'LAST', email: 'EMAIL' });
+ * ```
+ */
+export const createProfile = (params: ICreateProfileRequest) =>
+  getEndpoint()
+    .post<IProfile>('/profiles', params)
+    .then((r) => r.data);
+
+/**
+ * Get a profile. The caller must have admin access to the given profile.
+ * TODO: Add a "public" profile endpoint for public pages
+ *
+ * ```typescript
+ * import {Profiles} from '@verdocs/js-sdk/Users';
+ *
+ * const profile = await Profiles.getProfile('PROFILEID');
+ * ```
+ */
+export const getProfile = (profileId: string) =>
+  getEndpoint()
+    .get<IProfile>(`/profiles/${profileId}`)
+    .then((r) => r.data);
+
+/**
+ * Get a profile's permissions. The caller must have admin access to the given profile.
+ *
+ * ```typescript
+ * import {Profiles} from '@verdocs/js-sdk/Users';
+ *
+ * const permissions = await Profiles.getProfilePermissions('PROFILEID');
+ * ```
+ */
+export const getProfilePermissions = (profileId: string) =>
+  getEndpoint()
+    .get<IPermission[]>(`/profiles/${profileId}/permissions`)
+    .then((r) => r.data);
+
+/**
+ * Get a profile's groups.
+ *
+ * ```typescript
+ * import {Profiles} from '@verdocs/js-sdk/Users';
+ *
+ * const groups = await Profiles.getProfileGroups('PROFILEID');
+ * ```
+ */
+export const getProfileGroups = (profileId: string) =>
+  getEndpoint()
+    .get<IGroup[]>(`/profiles/${profileId}/groups`)
+    .then((r) => r.data);
+
+/**
+ * Switch the caller's "current" profile. The current profile is used for permissions checking and profile_id field settings
+ * for most operations in Verdocs. It is important to select the appropropriate profile before calling other API functions.
+ *
+ * ```typescript
+ * import {Profiles} from '@verdocs/js-sdk/Users';
+ *
+ * const newProfile = await Profiles.switchProfile('PROFILEID');
+ * ```
+ */
+export const switchProfile = (profileId: string) =>
+  getEndpoint()
+    .post<ISwitchProfileResponse>(`/profiles/${profileId}/switch`)
+    .then((r) => r.data);
+
+/**
+ * Update a profile. For future expansion, the profile ID to update is required, but currently this must also be the
+ * "current" profile for the caller.
+ *
+ * ```typescript
+ * import {Profiles} from '@verdocs/js-sdk/Users';
+ *
+ * const newProfile = await Profiles.updateProfile('PROFILEID');
+ * ```
+ */
+export const updateProfile = (profileId: string, params: IUpdateProfileRequest) =>
+  getEndpoint()
+    .put<IProfile>(`/profiles/${profileId}`, params)
+    .then((r) => r.data);
+
+/**
+ * Delete a profile. If the requested profile is the caller's curent profile, the next available profile will be selected.
+ *
+ * ```typescript
+ * import {Profiles} from '@verdocs/js-sdk/Users';
+ *
+ * await Profiles.deleteProfile('PROFILEID');
+ * ```
+ */
+export const deleteProfile = (profileId: string) =>
+  getEndpoint()
+    .delete(`/profiles/${profileId}`)
+    .then((r) => r.data);

package/src/Users/Types.ts

@@ -0,0 +1,156 @@
+import {IGroup, IOrganization} from '../Organizations/Types';
+import {TRequestStatus} from '../HTTP/Types';
+
+export type TPermission =
+  | 'org:view'
+  | 'member:view'
+  | 'org:update'
+  | 'member:add'
+  | 'member:remove'
+  | 'admin:add'
+  | 'admin:remove'
+  | 'org:delete'
+  | 'org:transfer'
+  | 'owner:add'
+  | 'owner:remove'
+  | 'template:creator:create:personal'
+  | 'template:creator:visibility'
+  | 'template:creator:create:org'
+  | 'template:member:read'
+  | 'template:member:write'
+  | 'template:member:visibility'
+  | 'template:creator:delete'
+  | 'template:member:delete'
+  | 'template:creator:create:public'
+  | 'rform:access'
+  | 'rcommon:access'
+  | 'org:list'
+  | 'org:create';
+
+export type TPlan = 'env:essential' | 'org:standard';
+
+export type TRole = 'owner' | 'basic_user' | 'member';
+
+export interface IProfile {
+  /** The unique ID of the profile */
+  id: string;
+  /**
+   * The Verdocs back-end currently uses Auth0 for authentication. This value is a unique ID assigned by Auth0 to the
+   * user. This is typically used to identify multiple profiles owned by a single user, but its implementation may
+   * change in the future and developers should not develop code based on this field at this time.
+   */
+  user_id: string;
+  /** The profile's organization ID, or a global "Realster" organization that all personal profiles are members of. */
+  organization_id: string;
+  first_name: string;
+  last_name: string;
+  email: string;
+  phone: string | null;
+  /** If true, this is the caller's "currently selected" profile. All operations will performed "as" this profile. */
+  current: boolean;
+  /** The organization */
+  organization: IOrganization;
+  /** The permissions assigned to the profilel _NOTE: Only present in the "current" profile._ */
+  permissions?: TPermission[];
+  /** The roles assigned to the profilel _NOTE: Only present in the "current" profile._ */
+  roles?: TRole[];
+  /** The plans assigned to the profilel _NOTE: Only present in the "current" profile._ */
+  plans?: TPlan[];
+  /** The plans assigned to the profilel _NOTE: Only present in the "current" profile._ */
+  groups?: IGroup[];
+}
+
+export interface IActiveSession {
+	  sub: string;
+	  email: string;
+	  email_verified: boolean;
+	  iat: number;
+	  exp: number;
+	  permissions: IPermission[];
+	  roles: IRole[];
+	  profile: IProfile;
+	  profile_id: string;
+	  organization_id: string;
+	  plans?: TPlan[];
+}
+
+export interface IRole {
+  /** Unique identifier for the role. */
+  id: string;
+  /** Display name for the role. */
+  name: string;
+}
+
+export interface IPermission {
+  /** Unique identifier for the permission. */
+  id: string;
+  /** Display name for the permission. */
+  name: string;
+}
+
+export interface ICreateProfileRequest {
+  first_name: string;
+  last_name: string;
+  email: string;
+  phone?: string;
+}
+
+export interface ISwitchProfileResponse {
+  profile: IProfile;
+  idToken: string;
+  accessToken: string;
+  refreshToken: string;
+}
+
+export interface IUpdateProfileRequest {
+  first_name?: string;
+  last_name?: string;
+  phone?: string;
+}
+
+export interface IAuthenticateUserRequest {
+  username: string;
+  password: string;
+}
+
+export interface IAuthenticateAppRequest {
+  client_id: string;
+  client_secret: string;
+}
+
+export interface IAuthenticateResponse {
+  idToken: string;
+  accessToken: string;
+  refreshToken: string;
+}
+
+export interface TokenValidationRequest {
+  token: string;
+}
+
+export interface TokenValidationResponse {
+  /** True if the token is valid */
+  valid: boolean;
+  /** The decoded and validated body of the JWT */
+  payload: any;
+}
+
+export interface UpdatePasswordRequest {
+  email: string;
+  oldPassword: string;
+  newPassword: string;
+}
+
+export interface UpdatePasswordResponse {
+  status: TRequestStatus;
+  /** Success or failure message */
+  message: string;
+}
+
+export interface UpdateEmailRequest {
+  email: string;
+}
+
+export interface UpdateEmailResponse {
+  profiles: IProfile[];
+}

package/src/Users/index.ts

@@ -0,0 +1,5 @@
+export * as Auth from './Auth';
+export * as Billing from './Billing';
+export * as Notifications from './Notifications';
+export * as Profiles from './Profiles';
+export * as Types from './Types';

package/src/Utils/DateTime.ts

@@ -0,0 +1,43 @@
+const YEAR = 365 * 24 * 60 * 60;
+const MONTH = 30 * 24 * 60 * 60;
+const WEEK = 7 * 24 * 60 * 60;
+const DAY = 24 * 60 * 60;
+const HOUR = 60 * 60;
+const MINUTE = 60;
+
+export const formatShortTimeAgo = (val: any) => {
+  if (val === undefined || val === null) {
+    return '';
+  }
+
+  let dateInput;
+  if (typeof val === 'string' || typeof val === 'number') {
+    dateInput = new Date(val);
+  } else if (typeof val === 'object') {
+    dateInput = val;
+  } else {
+    return '';
+  }
+
+  const timeDiff = Math.floor((new Date().getTime() - dateInput.getTime()) / 1000);
+  if (timeDiff >= YEAR) {
+    return Math.floor(timeDiff / YEAR) + 'Y';
+  }
+  if (timeDiff >= MONTH) {
+    return Math.floor(timeDiff / MONTH) + 'M';
+  }
+  if (timeDiff >= WEEK) {
+    return Math.floor(timeDiff / WEEK) + 'W';
+  }
+  if (timeDiff >= DAY) {
+    return Math.floor(timeDiff / DAY) + 'Y';
+  }
+  if (timeDiff >= HOUR) {
+    return Math.floor(timeDiff / HOUR) + 'Y';
+  }
+  if (timeDiff >= MINUTE) {
+    return Math.floor(timeDiff / MINUTE) + 'Y';
+  }
+
+  return `${timeDiff}S`;
+};

package/src/Utils/index.ts

@@ -0,0 +1 @@
+export * as DateTime from './DateTime';

package/src/Validators.ts

@@ -0,0 +1,16 @@
+import {getEndpoint} from './HTTP/Transport';
+
+export interface IValidator {
+  name: string;
+  regex: string;
+}
+
+export const getValidators = () =>
+  getEndpoint()
+    .get<IValidator[]>('/validators')
+    .then((r) => r.data);
+
+export const getValidator = (validatorName: string) =>
+  getEndpoint()
+    .get<IValidator>(`/validators/${validatorName}`)
+    .then((r) => r.data);

package/src/Whitelabel.ts

@@ -0,0 +1,11 @@
+import {getEndpoint} from './HTTP/Transport';
+
+export const createWhitelabel = () =>
+  getEndpoint()
+    .post('/whitelabel')
+    .then((r) => r.data);
+
+export const getWhitelabel = () =>
+  getEndpoint()
+    .get('/whitelabel')
+    .then((r) => r.data);

package/src/__tests__/Organizations/Apikeys.spec.ts

@@ -0,0 +1,84 @@
+import mockAxios from 'jest-mock-axios';
+import {ApiKeys} from '../../Organizations';
+import {IApiKey, IApiKeyWithSecret} from '../../Organizations/Types';
+
+afterEach(() => {
+  mockAxios.reset();
+});
+
+const MockKey = {
+  client_id: 'TEST',
+  name: 'TEST',
+  profile_id: 'TEST',
+  organization_id: 'TEST',
+} as IApiKey;
+
+const MockKeyWithSecret = {
+  client_id: 'TEST',
+  client_secret: 'TEST',
+  name: 'TEST',
+  profile_id: 'TEST',
+  organization_id: 'TEST',
+} as IApiKeyWithSecret;
+
+it('getKeys should return a list of keys for an organization', () => {
+  const catchFn = jest.fn();
+  const thenFn = jest.fn();
+
+  ApiKeys.getKeys('TEST').then(thenFn).catch(catchFn);
+  expect(mockAxios.get).toBeCalledWith('/organizations/TEST/api_key');
+
+  mockAxios.mockResponse({data: [MockKeyWithSecret]});
+  expect(thenFn).toBeCalledWith([MockKeyWithSecret]);
+  expect(catchFn).not.toBeCalled();
+});
+
+it('createKey should return a newly created key', () => {
+  const catchFn = jest.fn();
+  const thenFn = jest.fn();
+
+  const request = {name: 'TEST', profile_id: 'TEST'};
+  ApiKeys.createKey('TEST', request).then(thenFn).catch(catchFn);
+  expect(mockAxios.post).toBeCalledWith('/organizations/TEST/api_key', request);
+
+  mockAxios.mockResponse({data: MockKeyWithSecret});
+  expect(thenFn).toBeCalledWith(MockKeyWithSecret);
+  expect(catchFn).not.toBeCalled();
+});
+
+it('rotateKey should return an updated key with secret', () => {
+  const catchFn = jest.fn();
+  const thenFn = jest.fn();
+
+  ApiKeys.rotateKey('TEST', 'TEST').then(thenFn).catch(catchFn);
+  expect(mockAxios.put).toBeCalledWith('/organizations/TEST/api_key/TEST/rotate');
+
+  mockAxios.mockResponse({data: MockKeyWithSecret});
+  expect(thenFn).toBeCalledWith(MockKeyWithSecret);
+  expect(catchFn).not.toBeCalled();
+});
+
+it('updateKey should return an updated key without secret', () => {
+  const catchFn = jest.fn();
+  const thenFn = jest.fn();
+
+  const params = {name: 'TEST'};
+  ApiKeys.updateKey('TEST', 'TEST', params).then(thenFn).catch(catchFn);
+  expect(mockAxios.patch).toBeCalledWith('/organizations/TEST/api_key/TEST', params);
+
+  mockAxios.mockResponse({data: MockKey});
+  expect(thenFn).toBeCalledWith(MockKey);
+  expect(catchFn).not.toBeCalled();
+});
+
+it('deleteKey should succeed', () => {
+  const catchFn = jest.fn();
+  const thenFn = jest.fn();
+
+  ApiKeys.deleteKey('TEST', 'TEST').then(thenFn).catch(catchFn);
+  expect(mockAxios.delete).toBeCalledWith('/organizations/TEST/api_key/TEST');
+
+  mockAxios.mockResponse();
+  expect(thenFn).toBeCalled();
+  expect(catchFn).not.toBeCalled();
+});

package/src/__tests__/Users/Auth.spec.ts

@@ -0,0 +1,89 @@
+import mockAxios from 'jest-mock-axios';
+import {Auth} from '../../Users';
+
+afterEach(() => {
+  mockAxios.reset();
+});
+
+it('authenticateUser should return access tokens', () => {
+  const catchFn = jest.fn();
+  const thenFn = jest.fn();
+
+  const request = {username: 'test@test.com', password: 'PASSWORD'};
+  Auth.authenticateUser(request).then(thenFn).catch(catchFn);
+  expect(mockAxios.post).toBeCalledWith('/authentication/login', request);
+
+  const response = {accessToken: 'A', idToken: 'B', refreshToken: 'C'};
+  mockAxios.mockResponse({data: response});
+  expect(thenFn).toBeCalledWith(response);
+  expect(catchFn).not.toBeCalled();
+});
+
+it('authenticateApp should return access tokens', () => {
+  const catchFn = jest.fn();
+  const thenFn = jest.fn();
+
+  const headers = {client_id: 'CLIENTID', client_secret: 'SECRET'};
+  Auth.authenticateApp(headers).then(thenFn).catch(catchFn);
+  expect(mockAxios.post).toBeCalledWith('/authentication/login_client', {}, {headers});
+
+  const response = {accessToken: 'A', idToken: 'B', refreshToken: 'C'};
+  mockAxios.mockResponse({data: response});
+  expect(thenFn).toBeCalledWith(response);
+  expect(catchFn).not.toBeCalled();
+});
+
+it('validateToken should return access tokens', () => {
+  const catchFn = jest.fn();
+  const thenFn = jest.fn();
+
+  const request = {token: 'TOKEN'};
+  Auth.validateToken(request).then(thenFn).catch(catchFn);
+  expect(mockAxios.post).toBeCalledWith('/token/isValid', request);
+
+  const response = {valid: true};
+  mockAxios.mockResponse({data: response});
+  expect(thenFn).toBeCalledWith(response);
+  expect(catchFn).not.toBeCalled();
+});
+
+it('refreshTokens should return access tokens', () => {
+  const catchFn = jest.fn();
+  const thenFn = jest.fn();
+
+  Auth.refreshTokens().then(thenFn).catch(catchFn);
+  expect(mockAxios.get).toBeCalledWith('/token');
+
+  const response = {accessToken: 'A', idToken: 'B', refreshToken: 'C'};
+  mockAxios.mockResponse({data: response});
+  expect(thenFn).toBeCalledWith(response);
+  expect(catchFn).not.toBeCalled();
+});
+
+it('updatePassword should return a success message', () => {
+  const catchFn = jest.fn();
+  const thenFn = jest.fn();
+
+  const request = {email: 'EMAIL', oldPassword: 'OLD', newPassword: 'NEW'};
+  Auth.updatePassword(request).then(thenFn).catch(catchFn);
+  expect(mockAxios.put).toBeCalledWith('/user/update_password', request);
+
+  const response = {status: 'OK', message: 'Password has been updated.'};
+  mockAxios.mockResponse({data: response});
+  expect(thenFn).toBeCalledWith(response);
+  expect(catchFn).not.toBeCalled();
+});
+
+it("updateEmail should return the user's profiles", () => {
+  const catchFn = jest.fn();
+  const thenFn = jest.fn();
+
+  const request = {email: 'EMAIL'};
+  Auth.updateEmail(request).then(thenFn).catch(catchFn);
+  expect(mockAxios.put).toBeCalledWith('/user/update_email', request);
+
+  const response = {profiles: []};
+  mockAxios.mockResponse({data: response});
+  expect(thenFn).toBeCalledWith(response);
+  expect(catchFn).not.toBeCalled();
+});