Docs
TypeScript API
Services
HistoryService

HistoryService

Package: @vendure/core File: history.service.ts

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>;
}

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

Contents

Community

HistoryService

HistoryService

Custom History Entry Types

Signature

Members

constructor

getHistoryForOrder

createHistoryEntryForOrder

getHistoryForCustomer

createHistoryEntryForCustomer

updateOrderHistoryEntry

deleteOrderHistoryEntry

updateCustomerHistoryEntry

deleteCustomerHistoryEntry