🚨 Announcement: A New Chapter for Vendure read more

HistoryService

HistoryService

Contains methods relating to HistoryEntry entities. Histories are timelines of actions related to a particular Customer or Order, recording significant events such as creation, state changes, notes, etc.

Custom History Entry Types

Since Vendure v1.9.0, it is possible to define custom HistoryEntry types.

Let’s take an example where we have some Customers who are businesses. We want to verify their tax ID in order to allow them wholesale rates. As part of this verification, we’d like to add an entry into the Customer’s history with data about the tax ID verification.

First of all we’d extend the GraphQL HistoryEntryType enum for our new type as part of a plugin

Example

import { PluginCommonModule, VendurePlugin } from '@vendure/core';
import { VerificationService } from './verification.service';

@VendurePlugin({
  imports: [PluginCommonModule],
  adminApiExtensions: {
    schema: gql`
      extend enum HistoryEntryType {
        CUSTOMER_TAX_ID_VERIFICATION
      }
    `,
  },
  providers: [VerificationService],
})
export class TaxIDVerificationPlugin {}

Next we need to create a TypeScript type definition file where we extend the CustomerHistoryEntryData interface. This is done via TypeScript’s declaration merging and ambient modules features.

Example

// types.ts
import { CustomerHistoryEntryData } from '@vendure/core';

export const CUSTOMER_TAX_ID_VERIFICATION = 'CUSTOMER_TAX_ID_VERIFICATION';

declare module '@vendure/core' {
  interface CustomerHistoryEntryData {
    [CUSTOMER_TAX_ID_VERIFICATION]: {
      taxId: string;
      valid: boolean;
      name?: string;
      address?: string;
    };
  }
}

Note: it works exactly the same way if we wanted to add a custom type for Order history, except in that case we’d extend the OrderHistoryEntryData interface instead.

Now that we have our types set up, we can use the HistoryService to add a new HistoryEntry in a type-safe manner:

Example

// verification.service.ts
import { Injectable } from '@nestjs/common';
import { RequestContext } from '@vendure/core';
import { CUSTOMER_TAX_ID_VERIFICATION } from './types';

@Injectable()
export class VerificationService {
  constructor(private historyService: HistoryService) {}

  async verifyTaxId(ctx: RequestContext, customerId: ID, taxId: string) {
    const result = await someTaxIdCheckingService(taxId);

    await this.historyService.createHistoryEntryForCustomer({
      customerId,
      ctx,
      type: CUSTOMER_TAX_ID_VERIFICATION,
      data: {
        taxId,
        valid: result.isValid,
        name: result.companyName,
        address: result.registeredAddress,
      },
    });
  }
}

It is also possible to define a UI component to display custom history entry types. See the Custom History Timeline Components guide.

Signature

class HistoryService {
  constructor(connection: TransactionalConnection, administratorService: AdministratorService, listQueryBuilder: ListQueryBuilder, eventBus: EventBus)
  async getHistoryForOrder(ctx: RequestContext, orderId: ID, publicOnly: boolean, options?: HistoryEntryListOptions) => Promise<PaginatedList<OrderHistoryEntry>>;
  async createHistoryEntryForOrder(args: CreateOrderHistoryEntryArgs<T>, isPublic:  = true) => Promise<OrderHistoryEntry>;
  async getHistoryForCustomer(ctx: RequestContext, customerId: ID, publicOnly: boolean, options?: HistoryEntryListOptions) => Promise<PaginatedList<CustomerHistoryEntry>>;
  async createHistoryEntryForCustomer(args: CreateCustomerHistoryEntryArgs<T>, isPublic:  = false) => Promise<CustomerHistoryEntry>;
  async updateOrderHistoryEntry(ctx: RequestContext, args: UpdateOrderHistoryEntryArgs<T>) => ;
  async deleteOrderHistoryEntry(ctx: RequestContext, id: ID) => Promise<void>;
  async updateCustomerHistoryEntry(ctx: RequestContext, args: UpdateCustomerHistoryEntryArgs<T>) => ;
  async deleteCustomerHistoryEntry(ctx: RequestContext, id: ID) => Promise<void>;
}

Members

constructor

method
type:
(connection: TransactionalConnection, administratorService: AdministratorService, listQueryBuilder: ListQueryBuilder, eventBus: EventBus) => HistoryService

getHistoryForOrder

async method
type:
(ctx: RequestContext, orderId: ID, publicOnly: boolean, options?: HistoryEntryListOptions) => Promise<PaginatedList<OrderHistoryEntry>>

createHistoryEntryForOrder

async method
type:
(args: CreateOrderHistoryEntryArgs<T>, isPublic: = true) => Promise<OrderHistoryEntry>

getHistoryForCustomer

async method
type:
(ctx: RequestContext, customerId: ID, publicOnly: boolean, options?: HistoryEntryListOptions) => Promise<PaginatedList<CustomerHistoryEntry>>

createHistoryEntryForCustomer

async method
type:
(args: CreateCustomerHistoryEntryArgs<T>, isPublic: = false) => Promise<CustomerHistoryEntry>

updateOrderHistoryEntry

async method
type:
(ctx: RequestContext, args: UpdateOrderHistoryEntryArgs<T>) =>

deleteOrderHistoryEntry

async method
type:
(ctx: RequestContext, id: ID) => Promise<void>

updateCustomerHistoryEntry

async method
type:
(ctx: RequestContext, args: UpdateCustomerHistoryEntryArgs<T>) =>

deleteCustomerHistoryEntry

async method
type:
(ctx: RequestContext, id: ID) => Promise<void>