HistoryService

@vendure/core Source

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.tsimport { 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.tsimport { 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,      },    });  }}

Info

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)    getHistoryForOrder(ctx: RequestContext, orderId: ID, publicOnly: boolean, options?: HistoryEntryListOptions) => Promise<PaginatedList<OrderHistoryEntry>>;    createHistoryEntryForOrder(args: CreateOrderHistoryEntryArgs<T>, isPublic:  = true) => Promise<OrderHistoryEntry>;    getHistoryForCustomer(ctx: RequestContext, customerId: ID, publicOnly: boolean, options?: HistoryEntryListOptions) => Promise<PaginatedList<CustomerHistoryEntry>>;    createHistoryEntryForCustomer(args: CreateCustomerHistoryEntryArgs<T>, isPublic:  = false) => Promise<CustomerHistoryEntry>;    updateOrderHistoryEntry(ctx: RequestContext, args: UpdateOrderHistoryEntryArgs<T>) => ;    deleteOrderHistoryEntry(ctx: RequestContext, id: ID) => Promise<void>;    updateCustomerHistoryEntry(ctx: RequestContext, args: UpdateCustomerHistoryEntryArgs<T>) => ;    deleteCustomerHistoryEntry(ctx: RequestContext, id: ID) => Promise<void>;}

constructor

method

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

getHistoryForOrder

method

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

createHistoryEntryForOrder

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

getHistoryForCustomer

method

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

createHistoryEntryForCustomer

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

updateOrderHistoryEntry

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

deleteOrderHistoryEntry

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

updateCustomerHistoryEntry

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

deleteCustomerHistoryEntry

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