@verdocs/js-sdk 1.0.8 → 1.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verdocs/js-sdk",
-  "version": "1.0.8",
+  "version": "1.0.12",
   "private": false,
   "homepage": "https://github.com/Verdocs/js-sdk",
   "description": "Verdocs JS SDK",
@@ -26,7 +26,9 @@
     "url": "https://github.com/Verdocs/js-sdk/issues"
   },
   "scripts": {
-    "build": "tsc && cp README.md package.json .npmignore dist",
+    "build": "rm -rf dist/* && tsc && cp README.md package.json .npmignore dist",
+    "Xprepare": "npm run build",
+    "XprepublishOnly": "npm test && npm run lint",
     "preversion": "npm run lint",
     "version": "npm run format && git add -A src",
     "postversion": "git push && git push --tags",
@@ -35,7 +37,8 @@
     "lint": "tslint -p tsconfig.json",
     "docs-md": "typedoc && git add --all docs",
     "docs-html": "typedoc --plugin none --out docs-html",
-    "docs": "npm run docs-md && npm run docs-html && cp -aR docs-html/* ../partner-portal/site/static/js-sdk/"
+    "docs": "npm run docs-md && npm run docs-html && cp -aR docs-html/* ../partner-portal/site/static/js-sdk/",
+    "pub": "npm version patch && npm run build && npm run docs"
   },
   "publishConfig": {
     "access": "public"

package/src/Documents/Documents.ts

@@ -0,0 +1,166 @@
+import {getEndpoint} from '../HTTP/Transport';
+
+export type IDocumentStatus = 'complete' | 'pending' | 'progress';
+
+export type IRecipientStatus = 'invited' | 'opened' | 'signed' | 'submitted';
+
+export type IRecipientType = 'signer' | 'cc';
+
+export interface IDocumentsSearchResultEntry {
+  id: string;
+  canceled_at: string;
+  created_at: string;
+  name: string;
+  profile_id: string;
+  status: IDocumentStatus;
+  next_recipient: {
+    claimed: boolean;
+    email: string;
+    name: string;
+    profile_id: string;
+    status: IRecipientStatus;
+    type: IRecipientType;
+  };
+  template_id: string;
+  total_count: number;
+  updated_at: string;
+}
+
+export interface IDocumentsSearchResult {
+  page: number;
+  total: number;
+  result: IDocumentsSearchResultEntry[];
+}
+
+export interface IDocumentsSummary {
+  action_required: {
+    page: number;
+    total: number;
+    result: IActivityEntry[];
+  };
+  completed: {
+    page: number;
+    total: number;
+    result: IActivityEntry[];
+  };
+  waiting_others: {
+    page: number;
+    total: number;
+    result: IActivityEntry[];
+  };
+}
+
+export interface IRecipient {
+  agreed: boolean;
+  claimed: boolean;
+  created_at: string;
+  delegated_to: string | null;
+  delegator: boolean;
+  email: string;
+  envelope_id: string;
+  full_name: string;
+  in_app_access_key: string;
+  key_used_to_conclude: string;
+  message: string | null;
+  phone: string;
+  profile_id: string;
+  role_name: string;
+  sequence: number;
+  status: IRecipientStatus;
+  type: IRecipientType;
+  updated_at: string;
+}
+
+export interface IDocument {
+  id: string;
+  created_at: string;
+  canceled_at: string;
+  envelope_document_id: string;
+  certificate_document_id: string | null;
+  histories: IHistory[];
+  recipients: IRecipient[];
+  name: string;
+  no_contact: boolean;
+  profile_id: string;
+  reminder_id: string | null;
+  status: IDocumentStatus;
+  template_id: string;
+  updated_at: string;
+  organization_id: string | null;
+}
+
+export interface IActivityEntry {
+  id: string;
+  name: string;
+  canceled_at: string;
+  created_at: string;
+  updated_at: string;
+  profile_id: string;
+  status: IDocumentStatus;
+  template_id: string;
+  recipient: {
+    claimed: boolean;
+    email: string;
+    name: string;
+    profile_id: string;
+    status: IRecipientStatus;
+    type: IRecipientType;
+  };
+}
+
+export interface IHistory {
+  created_at: string;
+  envelope_id: string;
+  event: IHistoryEvent;
+  event_detail: IEventDetail;
+  id: string;
+  role_name: string;
+}
+
+export interface IDocumentSearchOptions {
+  rows?: number;
+  page?: number;
+  sort_by?: 'updated_at' | 'created_at';
+  ascending?: boolean;
+  is_owner?: boolean;
+  is_recipient?: boolean;
+  envelope_status: IDocumentStatus[];
+  recipient_status: IDocumentStatus[];
+}
+
+export type IHistoryEvent =
+  | 'recipient:invited'
+  | 'recipient:opened'
+  | 'recipient:agreed'
+  | 'recipient:signed'
+  | 'recipient:submitted';
+
+export type IEventDetail = 'in_app' | 'mail' | 'signer' | '';
+
+/**
+ * Get a summary of currently active documents.
+ *
+ * ```typescript
+ * import {Documents} from '@verdocs/js-sdk/Documents';
+ *
+ * const {action_required, completed, waiting_on_others} = await Documents.getSummary();
+ * ```
+ */
+export const getSummary = async (page: number) =>
+  getEndpoint()
+    .post<IDocumentsSummary>('/documents/summary', {page})
+    .then((r) => r.data);
+
+/**
+ * Search for documents matching various criteria.
+ *
+ * ```typescript
+ * import {Documents} from '@verdocs/js-sdk/Documents';
+ *
+ * const {result, page, total} = await Documents.search({ ... });
+ * ```
+ */
+export const search = async (params: any) =>
+  getEndpoint()
+    .post<IDocumentsSearchResult>('/documents/search', params)
+    .then((r) => r.data);

package/src/Documents/Stars.ts

@@ -0,0 +1,5 @@
+import {getEndpoint} from '../HTTP/Transport';
+import {ITemplateSummaryEntry} from './Types';
+
+export const toggleStar = async (templateId: string) =>
+  getEndpoint().post<ITemplateSummaryEntry>(`/templates/${templateId}/stars/toggle`).then((r) => r.data);

package/src/Documents/Templates.ts

@@ -0,0 +1,17 @@
+import {getEndpoint} from '../HTTP/Transport';
+import {ITemplatesSummary} from './Types';
+
+export const getTemplates = async () =>
+  getEndpoint()
+    .get('/templates')
+    .then((r) => r.data);
+
+export const searchTemplates = async () =>
+  getEndpoint()
+    .post('/templates/search')
+    .then((r) => r.data);
+
+export const getSummary = async (page: number): Promise<ITemplatesSummary> =>
+  getEndpoint()
+    .post('/templates/summary', {page})
+    .then((r) => r.data);

package/src/Documents/Types.ts

@@ -0,0 +1,24 @@
+export interface ITemplateSummaryEntry {
+  id: string;
+  name: string;
+  sender: string;
+  counter: number;
+  description: string | null;
+  created_at: string;
+  updated_at: string;
+  is_personal: boolean;
+  is_public: boolean;
+  profile_id: string;
+  organization_id: string;
+  last_used_at: string | null;
+  document_name: string | null;
+  star_counter: number;
+  tag_name: string | null;
+  is_starred: boolean;
+}
+
+export interface ITemplatesSummary {
+  page: number;
+  total: number;
+  result: ITemplateSummaryEntry[];
+}

package/src/Documents/index.ts

@@ -0,0 +1,4 @@
+export * as Documents from './Documents';
+export * as Stars from './Stars';
+export * as Templates from './Templates';
+export * as Types from './Types';

package/src/HTTP/Transport.ts

@@ -0,0 +1,95 @@
+import axios from 'axios';
+
+const config = {
+  baseURL: 'https://api.verdocs.com/',
+  timeout: 3000,
+  headers: {'X-Client-ID': 'NONE'} as Record<string, string>,
+};
+let endpoint = axios.create(config);
+
+/**
+ * Set the auth token that will be used for Verdocs API calls.
+ *
+ * ```typescript
+ * import {Transport} from '@verdocs/js-sdk/HTTP';
+ *
+ * Transport.setAuthorization(accessToken);
+ * ```
+ */
+export const setAuthorization = (accessToken: string | null) => {
+  if (accessToken) {
+    config.headers['Authorization'] = `Bearer ${accessToken}`;
+  } else {
+    delete config.headers['Authorization'];
+  }
+
+  if (endpoint) {
+    endpoint = axios.create(config);
+  }
+};
+
+/**
+ * Set the Client ID for Verdocs API calls.
+ *
+ * ```typescript
+ * import {Transport} from '@verdocs/js-sdk/HTTP';
+ *
+ * Transport.setClientID('1234);
+ * ```
+ */
+export const setClientID = (clientID: string) => {
+  config.headers['X-Client-ID'] = clientID;
+  if (endpoint) {
+    endpoint = axios.create(config);
+  }
+};
+
+/**
+ * Set the base URL for API calls. Typically this is https://api.verdocs.com/ and is the default. Change this only after consultation
+ * with Verdocs Developer Support.
+ *
+ * ```typescript
+ * import {Transport} from '@verdocs/js-sdk/HTTP';
+ *
+ * Transport.setBaseUrl('https://api.verdiocs.com');
+ * ```
+ */
+export const setBaseUrl = (baseUrl: string) => {
+  config.baseURL = baseUrl;
+  if (endpoint) {
+    endpoint = axios.create(config);
+  }
+};
+
+/**
+ * Set the timeout for API calls in milliseconds. 2000-4000ms is recommended for most purposes. 3000ms is the default.
+ *
+ * ```typescript
+ * import {Transport} from '@verdocs/js-sdk/HTTP';
+ *
+ * Transport.setTimeout(3000);
+ * ```
+ */
+export const setTimeout = (timeout: number) => {
+  config.timeout = timeout;
+  if (endpoint) {
+    endpoint = axios.create(config);
+  }
+};
+
+/**
+ * Helper to get the endpoint for direct access to HTTP functions.
+ *
+ * ```typescript
+ * import {Transport} from '@verdocs/js-sdk/HTTP';
+ *
+ * console.log('Current timeout', Transport.getEndpoint().defaults.timeout);
+ * ```
+ */
+export const getEndpoint = () => {
+  if (!endpoint) {
+    endpoint = axios.create(config);
+  }
+
+  return endpoint;
+};

package/src/HTTP/Types.ts

@@ -0,0 +1 @@
+export type TRequestStatus = 'OK' | 'ERROR';

package/src/HTTP/index.ts

@@ -0,0 +1,2 @@
+export * as Transport from './Transport';
+export * as Types from './Types';

package/src/Organizations/ApiKeys.ts

@@ -0,0 +1,85 @@
+/**
+ * API keys are used to authenticate server-to-server calls. (API keys should **never** be used for client-to-server operations!)
+ * To generate a key, either use the Verdocs admin interface and make note of the client_id and client_secret generated, or call
+ * createKey as shown below. Then call {@link Users.Auth.authenticateApp} to obtain an access token using the provided ID and
+ * secret. Note that server-to-server authentication requests return shorter-lived tokens, so it is important to check the `exp`
+ * field and re-authenticate as needed for subsequent calls.
+ *
+ * API keys may be updated or rotated at any time. Regular rotation is recommended. Rotation will not expire or invalidate
+ * existing server-to-server sessions, so it may be done at any time without disrupting your application.
+ *
+ * @module
+ */
+
+import {getEndpoint} from '../HTTP/Transport';
+import {IApiKey, IApiKeyWithSecret, ICreateApiKeyRequest, IUpdateApiKeyRequest} from './Types';
+
+/**
+ * Get a list of keys for a given organization. The caller must have admin access to the organization.
+ *
+ * ```typescript
+ * import {ApiKeys} from '@verdocs/js-sdk/Organizations';
+ *
+ * const keys = await ApiKeys.getKeys(ORGID);
+ * ```
+ */
+export const getKeys = (organizationId: string) =>
+  getEndpoint()
+    .get<IApiKey[]>(`/organizations/${organizationId}/api_key`)
+    .then((r) => r.data);
+
+/**
+ * Create an API key.
+ *
+ * ```typescript
+ * import {ApiKeys} from '@verdocs/js-sdk/Organizations';
+ *
+ * await ApiKeys.createKey(ORGID, {name: NEWNAME});
+ * ```
+ */
+export const createKey = (organizationId: string, params: ICreateApiKeyRequest) =>
+  getEndpoint()
+    .post<IApiKeyWithSecret>(`/organizations/${organizationId}/api_key`, params)
+    .then((r) => r.data);
+
+/**
+ * Rotate the secret for an API key. The caller must have admin access to the organization.
+ *
+ * ```typescript
+ * import {ApiKeys} from '@verdocs/js-sdk/Organizations';
+ *
+ * const {client_secret: newSecret} = await ApiKeys.rotateKey(ORGID, CLIENTID);
+ * ```
+ */
+export const rotateKey = (organizationId: string, clientId: string) =>
+  getEndpoint()
+    .put<IApiKeyWithSecret>(`/organizations/${organizationId}/api_key/${clientId}/rotate`)
+    .then((r) => r.data);
+
+/**
+ * Update an API key to change its assigned Profile ID or Name.
+ *
+ * ```typescript
+ * import {ApiKeys} from '@verdocs/js-sdk/Organizations';
+ *
+ * await ApiKeys.updateKey(ORGID, CLIENTID, {name: NEWNAME});
+ * ```
+ */
+export const updateKey = (organizationId: string, clientId: string, params: IUpdateApiKeyRequest) =>
+  getEndpoint()
+    .patch<IApiKey>(`/organizations/${organizationId}/api_key/${clientId}`, params)
+    .then((r) => r.data);
+
+/**
+ * Delete an API key.
+ *
+ * ```typescript
+ * import {ApiKeys} from '@verdocs/js-sdk/Organizations';
+ *
+ * await ApiKeys.deleteKey(ORGID, CLIENTID);
+ * ```
+ */
+export const deleteKey = (organizationId: string, clientId: string) =>
+  getEndpoint()
+    .delete(`/organizations/${organizationId}/api_key/${clientId}`)
+    .then((r) => r.data);

package/src/Organizations/Groups.ts

@@ -0,0 +1,65 @@
+/**
+ * Organizations may contain "Groups" of user profiles, called Members. Groups may have permissions assigned that
+ * apply to all Members, making it easy to configure role-based access control (RBAC) within an Organization. Note
+ * that permissions are **additive**. A user may be a member of more than one group, and may also have permissions
+ * assigned directly. In that case, the user will have the combined set of all permissions inherited from all
+ * sources.
+ *
+ * @module
+ */
+
+import {getEndpoint} from '../HTTP/Transport';
+import {IGroup, IGroupDetail} from './Types';
+
+/**
+ * Get a list of groups for a given organization. The caller must have admin access to the organization.
+ *
+ * ```typescript
+ * import {Groups} from '@verdocs/js-sdk/Organizations';
+ *
+ * const groups = await Groups.getGroups(ORGID);
+ * ```
+ */
+export const getGroups = (organizationId: string) =>
+  getEndpoint()
+    .get<IGroup[]>(`/organizations/${organizationId}/groups`)
+    .then((r) => r.data);
+
+/**
+ * Get the details for a group.
+ *
+ * ```typescript
+ * import {Groups} from '@verdocs/js-sdk/Organizations';
+ *
+ * const groups = await Groups.getGroups(ORGID);
+ * ```
+ */
+export const getGroup = (organizationId: string, groupId: string) =>
+  getEndpoint()
+    .get<IGroupDetail>(`/organizations/${organizationId}/groups/${groupId}`)
+    .then((r) => r.data);
+
+export const getMembers = (organizationId: string, groupId: string) =>
+  getEndpoint()
+    .get(`/organizations/${organizationId}/groups/${groupId}/members`)
+    .then((r) => r.data);
+
+export const addMembers = (organizationId: string, groupId: string, params: any) =>
+  getEndpoint()
+    .post(`/organizations/${organizationId}/groups/${groupId}/members`, params)
+    .then((r) => r.data);
+
+export const deleteMembers = (organizationId: string, groupId: string, params: any) =>
+  getEndpoint()
+    .put(`/organizations/${organizationId}/groups/${groupId}/delete_members`, params)
+    .then((r) => r.data);
+
+export const addPermission = (organizationId: string, groupId: string, permissionId: string, params: any) =>
+  getEndpoint()
+    .post(`/organizations/${organizationId}/groups/${groupId}/permissions/${permissionId}`, params)
+    .then((r) => r.data);
+
+export const deletePermission = (organizationId: string, groupId: string, permissionId: string) =>
+  getEndpoint()
+    .delete(`/organizations/${organizationId}/groups/${groupId}/permissions/${permissionId}`)
+    .then((r) => r.data);

package/src/Organizations/Invitations.ts

@@ -0,0 +1,36 @@
+import {getEndpoint} from '../HTTP/Transport';
+
+export const getInvitations = (organizationId: string) =>
+  getEndpoint()
+    .get(`/organizations/${organizationId}/invitation`)
+    .then((r) => r.data);
+
+export const createInvitation = (organizationId: string, params: any) =>
+  getEndpoint()
+    .post(`/organizations/${organizationId}/invitation`, params)
+    .then((r) => r.data);
+
+export const deleteInvitation = (organizationId: string, email: string) =>
+  getEndpoint()
+    .delete(`/organizations/${organizationId}/invitation/${email}`)
+    .then((r) => r.data);
+
+export const updateInvitation = (organizationId: string, email: string, params: any) =>
+  getEndpoint()
+    .patch(`/organizations/${organizationId}/invitation/${email}`, params)
+    .then((r) => r.data);
+
+export const resendInvitation = (organizationId: string, email: string) =>
+  getEndpoint()
+    .post(`/organizations/${organizationId}/invitation/${email}/resend`)
+    .then((r) => r.data);
+
+export const claimInvitation = (organizationId: string, email: string, params: any) =>
+  getEndpoint()
+    .put(`/organizations/${organizationId}/invitation/${email}`, params)
+    .then((r) => r.data);
+
+export const claimNewUser = (organizationId: string, email: string, token: string) =>
+  getEndpoint()
+    .put(`/organizations/${organizationId}/invitation/${email}/token/${token}/new_user`)
+    .then((r) => r.data);

package/src/Organizations/Members.ts

@@ -0,0 +1,26 @@
+import {getEndpoint} from '../HTTP/Transport';
+
+export const getMembers = (organizationId: string) =>
+  getEndpoint()
+    .get(`/organizations/${organizationId}/profiles`)
+    .then((r) => r.data);
+
+export const deleteMember = (organizationId: string, profileId: string) =>
+  getEndpoint()
+    .delete(`/organizations/${organizationId}/profiles/${profileId}`)
+    .then((r) => r.data);
+
+export const addMemberRole = (organizationId: string, profileId: string, roleId: string) =>
+  getEndpoint()
+    .post(`/organizations/${organizationId}/profiles/${profileId}/roles/${roleId}`)
+    .then((r) => r.data);
+
+export const deleteMemberRole = (organizationId: string, profileId: string, roleId: string) =>
+  getEndpoint()
+    .delete(`/organizations/${organizationId}/profiles/${profileId}/roles/${roleId}`)
+    .then((r) => r.data);
+
+export const getMemberPlans = (organizationId: string, profileId: string) =>
+  getEndpoint()
+    .get(`/organizations/${organizationId}/profiles/${profileId}/plans`)
+    .then((r) => r.data);

package/src/Organizations/Organizations.ts

@@ -0,0 +1,32 @@
+import {getEndpoint} from '../HTTP/Transport';
+import {IOrganization} from './Types';
+
+export const getOrganizations = () =>
+  getEndpoint()
+    .get<IOrganization[]>('/organizations')
+    .then((r) => r.data);
+
+export const createOrganization = () =>
+  getEndpoint()
+    .post<IOrganization>('/organizations')
+    .then((r) => r.data);
+
+export const validateOrganization = () =>
+  getEndpoint()
+    .get<IOrganization>('/organizations/is_valid')
+    .then((r) => r.data);
+
+export const deleteOrganization = (organizationId: string) =>
+  getEndpoint()
+    .delete(`/organizations/${organizationId}`)
+    .then((r) => r.data);
+
+export const getOrganization = (organizationId: string) =>
+  getEndpoint()
+    .get(`/organizations/${organizationId}`)
+    .then((r) => r.data);
+
+export const updateOrganization = (organizationId: string, params: any) =>
+  getEndpoint()
+    .patch(`/organizations/${organizationId}`, params)
+    .then((r) => r.data);

package/src/Organizations/Types.ts

@@ -0,0 +1,63 @@
+import {IProfile, TPermission, TRole} from '../Users/Types';
+
+export interface IOrganization {
+  /** The unique ID of the organization */
+  id: string;
+  /** The organization's name. */
+  name: string;
+  address: string | null;
+  phone: string | null;
+  /** If the organization is a business, its name. Note that a business name can be different from an organization name. */
+  business_name: string | null;
+  /** If true, the organization is a business */
+  is_business: boolean;
+  address2: string | null;
+  contact_email: string | null;
+  timezone: string | null;
+  envelope_responsible: boolean;
+}
+
+export interface ICreateApiKeyRequest {
+  name: string;
+  profile_id: string;
+}
+
+export interface IUpdateApiKeyRequest {
+  name?: string;
+  profile_id?: string;
+}
+
+export interface IApiKey {
+  client_id: string;
+  name: string;
+  profile_id: string;
+  organization_id: string;
+}
+
+export interface IApiKeyWithSecret extends IApiKey {
+  client_id: string;
+  client_secret: string;
+  name: string;
+  profile_id: string;
+  organization_id: string;
+}
+
+export interface IGroup {
+  id: string;
+  name: string;
+  organization_id: string;
+  /** For future expansion. In the future, Verdocs may support group hierarchies. Until then this field is always null. */
+  parent_id: string | null;
+  /** Some operations will additionally return a list of permissions. */
+  permissions?: TPermission[];
+  /** Some operations will additionally return a list of roles. */
+  roles?: TRole[];
+  /** Some operations will additionally return a list of profiles. */
+  profiles?: IProfile[];
+}
+
+export interface IGroupDetail extends IGroup {
+  permissions: TPermission[];
+  roles: TRole[];
+  profiles: IProfile[];
+}

package/src/Organizations/Webhooks.ts

@@ -0,0 +1,11 @@
+import {getEndpoint} from '../HTTP/Transport';
+
+export const getWebhook = (organizationId: string) =>
+  getEndpoint()
+    .get(`/organizations/${organizationId}/webhook`)
+    .then((r) => r.data);
+
+export const updateWebhook = (organizationId: string, params: any) =>
+  getEndpoint()
+    .post(`/organizations/${organizationId}/webhook`, params)
+    .then((r) => r.data);