/SipTwo

A strongly-typed library for communicating with SIP2 servers

Primary LanguageTypeScriptMIT LicenseMIT

SipTwo

SipTwo is a strongly-typed SIP2 wrapper for Node, written in Typescript.

Description

SipTwo is heavily inspired by Frank Desmettre's node-sip2 package--particularly message construction and interpretation.

SipTwo is written entirely in Typescript, so it can be easily integrated into your type-safe projects. Or you can use it in a plain vanilla javascript project and typings will be ignored. All server responses have been cast to their appropriate types: number, Date, string, boolean, etc.

SipTwo also provides an API that will be familiar to people used to working with ES6+. You can take advantage of async/await to eliminate the need for callbacks.

Features

  • Strong typed DTOs and responses
  • Manages sequence numbers automatically
  • Automatic error checking; provides a checksumValid: boolean with every response
  • Performs an SCStatus check upon server connection to determine message support. Will throw an exception if the calling application tries to use a feature not supported by the server
  • Exported interfaces for all DTOs and responses

What is SIP2?

SIP2 is a network protocol designed by 3M so that automated self-check machines could talk to an integrated library server (ILS). Since its creation, it has become widely used in a variety of different applications, for better or for worse.

Getting Started

Getting started is very straightforward. Instantiate the SipTwo class with an ISip2ConnectionOptions object and use the setPatron method to pass IPatronCredentials. You can call setPatron any time to select a different patron.

Connection objects:

import { SipTwo, ISip2ConnectionOptions, IPatronCredentials } from 'siptwo';

const sip2ConnectionOptions: ISip2ConnectionOptions = {
  host: '192.168.0.10',
  username: 'sip_user',
  password: 'sip_password',
  institutionId: 'sip_org',
};

const patronCredentials: IPatronCredentials = {
  patronIdentifier: 'patron_barcode',
  password: 'patron_pin',
  institutionId: 'patron_org',
};

Instantiate the class and make method calls:

const sipTwo = new SipTwo(sip2ConnectionOptions);

// Inside an async function/method
(async () => {

  await sipTwo.login();
  sipTwo.setPatron(patronCredentials);

  const patronInfo = await sipTwo.requestPatronInformation();
  console.log('patronInfo', patronInfo);

  sipTwo.connection.close();
})();

This will output a result similar to the following, bound to the IPatronInformationResponse interface:

patronInfo {
  status: PatronStatus {
    chargePrivilegesDenied: false,
    renewalPrivilegesDenied: false,
    recallPrivilegesDenied: true,
    holdPrivilegesDenied: false,
    cardReportedLost: false,
    tooManyItemsCharged: false,
    tooManyItemsOverdue: false,
    tooManyRenewals: false,
    tooManyClaimsOfItemsReturned: false,
    tooManyItemsLost: false,
    excessiveOutstandingFines: false,
    excessiveOutstandingFees: false,
    recallOverdue: false,
    tooManyItemsBilled: false
  },
  language: 'english',
  transactionDate: 2021-03-16T16:36:34.000Z,
  holdItemsCount: 3,
  overdueItemsCount: 0,
  chargedItemsCount: 1,
  fineItemsCount: 0,
  recallItemsCount: 0,
  unavailableHoldsCount: 0,
  institutionId: 'patron_org',
  patronIdentifier: 'patron_barcode',
  personalName: 'Gene Adams',
  feeAmount: 1.25,
  feeLimit: 0,
  homeAddress: '8265 Phone Trail El paso, El paso TX USA 88525',
  email: 'genesadams@gmail.com',
  phone: '538-342-5233',
  screenMessage: [],
  printLine: [],
  validPatron: true,
  validPatronUsed: true,
  validPatronPassword: false,
  validPatronPasswordUsed: true,
  currencyType: 'USD',
  sequence: 2,
  checksum: 'BA8B',
  checksumIsValid: true
}

Method Reference

The following is a list of exposed methods available through the SipTwo class. Refer to the corresponding interface files to see what the relevant object structure looks like.

Manage SIP2 socket connection

connection.connect(): Promise<void>
connection.close(): void
connection.send(request: string): Promise<any>

Log in to SIP2 server

login(): Promise<ILoginResponse>

Set patron credentials

setPatron(patronCredentials: IPatronCredentials)

Request resend

requestResend(): Promise<any>
  • Response: depends on previous message call

SC/ACS status

requestSCStatus(scStatusRequestDto: ISCStatusRequestDto = {}): Promise<IACStatusResponse>

Enable patron (if blocked)

requestPatronEnable(): Promise<IPatronEnableResponse>

Block patron

requestPatronBlock(blockPatronRequestDto: IBlockPatronRequestDto): Promise<IPatronStatusResponse>

Patron information

requestPatronInformation(): Promise<IPatronInformationResponse>

Patron status

requestPatronStatus(): Promise<IPatronStatusResponse>

Item information

requestItemInformation(itemIdentifier: string): Promise<IItemInformationResponse>

Checkout an item

requestCheckout(checkoutRequestDto: ICheckoutRequestDto): Promise<ICheckoutResponse>

Checkin an item

requestCheckin(checkinRequestDto: ICheckinRequestDto): Promise<ICheckinResponse>

Renew an item

requestRenew(renewRequestDto: IRenewRequestDto): Promise<IRenewResponse>

Renew all items

requestRenewAll(renewAllRequestDto: IRenewAllRequestDto = {}): Promise<IRenewAllResponse>

Pay fees

requestFeePaid(feePaidRequestDto: IFeePaidRequestDto): Promise<IFeePaidResponse>

Place a hold

requestHold(holdRequestDto: IHoldRequestDto): Promise<IHoldResponse>

End patron session

requestEndPatronSession(): Promise<IEndPatronSessionResponse>