@b-jones-rfd/sp-rest-connect

Sharepoint REST Connect

Use SharePoint Rest Services to interact with lists and document libraries. I got tired of rewriting these for work projects. Still building and not ready for use.

Prerequisites

This project requires NodeJS and NPM. Node and NPM are really easy to install. To make sure you have them available on your machine, try running the following command.

$ npm -v && node -v
10.2.4
v20.11.1

[PNPM] (https://pnpm.io/) is a awesome alternative to NPM and is recommended.

Table of contents

• SP REST Connect
  • Prerequisites
  • Table of contents
  • Getting Started
  • Installation
  • Usage
  • API
    • createSiteConnection
    • Actions
    • Responses
  • Contributing
  • Versioning
  • Authors
  • License

Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

Installation

BEFORE YOU INSTALL: please read the prerequisites

To install and set up the library, run:

$ npm i @b-jones-rfd/sp-rest-connect

Or if you prefer using Yarn:

$ yarn add @b-jones-rfd/sp-rest-connect

Or for PNPM:

$ pnpm add @b-jones-rfd/sp-rest-connect

Usage

Instance Methods

Actions can be performed against site collection lists or document libraries using instance methods on a SiteCollection instance.

import { createSiteConnection } from '@b-jones-rfd/sp-rest-connect'

const siteConnectionOptions = {
  username: 'tim',
  password: 'myexceptionalsecurepassword',
  site: 'my.sharepoint.com',
  serverRelativeUrl: '/path/to/my/site',
  protocol: 'https' as const,
}

const connection: SiteConnection = createSiteConnection(siteConnectionOptions)

const params = new URLSearchParams({
  $select: 'Id,Title',
  $top: '200',
})

async function getMyListUsingConnection(listName: string) {
  const contents = await connection.getListContents({ listName, params })
  if (contents.success) return contents.data
  else throw new Error(contents.error)
}

Factory Action Methods

Additionally, for single use or reduced import size, action factory methods can be imported directly. Call the factory method with a SiteConnectionOptions object to return an asynchronous action function that can be called directly.

import { getListContents } from '@b-jones-rfd/sp-rest-connect'

async function getMyListUsingAction(listName: string) {
  const action = getListContents(connectionOpts)
  const contents = await action({ listName, params })
  if (contents.success) return contents.data
  else throw new Error(contents.error)
}

API

createSiteConnection

SiteConnectionOptions

username

Type	Description	Example
string	SharePoint username	'user'

password

Type	Description
string	SharePoint password

site

Type	Description	Example
string	SharePoint domain	sharepoint.domain.com

serverRelativeUrl

Type	Description	Example
string	SharePoint site relative Url	/path/to/my/site

protocol

Type	Default value	Options	Description
string	'https'	'http' or 'http'	Site protocol

domain

Type	Default value	Description
string	''	NTLM domain

hostname

Type	Default value	Description
string	os.hostname()	OS Hostname

Actions

SiteConnection instance action methods.

export type Action<TConfig, TResponse> = (
  options: TConfig
) => Promise<Result<TResponse>>

If using the actions directly call the factory method with a SiteConnectionOptions object to return an action that can be used to execute a SharePoint action.

addAttachmentToListItem(options)

options

Property	Type	Description	Required
accessToken	string	SharePoint access token	Y
listName	string	SharePoint list name	Y
spId	number	SharePoint list item ID	Y
fileName	string	File name	Y
payload	Buffer	File contents	Y

addDocumentToLibrary(options)

options

Property	Type	Description	Required
accessToken	string	SharePoint access token	Y
folder	string	SharePoint folder name	Y
fileName	string	File name	Y
payload	Buffer	File contents	Y

addListItem(options)

options

Property	Type	Description	Required
accessToken	string	SharePoint access token	Y
listName	string	SharePoint list name	Y
payload	string	List item JSON as string	Y

checkFolderExistsInLibrary(options)

options

Property	Type	Description	Required
folder	string	SharePoint folder/subfolder name	Y

createFolderInLibrary(options)

options

Property	Type	Description	Required
accessToken	string	SharePoint access token	Y
folder	string	SharePoint folder/subfolder name	Y

deleteDocumentFromLibrary(options)

options

Property	Type	Description	Required
accessToken	string	SharePoint access token	Y
folder	string	SharePoint folder/subfolder name	Y
fileName	string	File name	Y

deleteListItem(options)

options

Property	Type	Description	Required
accessToken	string	SharePoint access token	Y
listName	string	SharePoint list name	Y
spId	number	SharePoint list item ID	Y

getAuthToken()

getFormDigestValue()

getDocumentFromLibrary(options)

options

Property	Type	Description	Required
folder	string	SharePoint folder name	Y
fileName	string	File name	Y

getListContents(options)

options

Property	Type	Description	Required
listName	string	SharePoint list name	Y
params	UrlSearchParams	SharePoint list name	N

getListItem(options)

options

Property	Type	Description	Required
listName	string	SharePoint list name	Y
spId	number	SharePoint list item ID	Y

getListItemType(options)

options

Property	Type	Description	Required
listName	string	SharePoint list name	Y

updateListItem(options)

options

Property	Type	Description	Required
accessToken	string	SharePoint access token	Y
listName	string	SharePoint list name	Y
spId	number	SharePoint list item ID	Y
patch	string	Updated list item JSON as string	Y

Responses

Responses are provided based on the Result type. Success can be determined by checking the success property.

export type Result<TResponse> = Success<TResponse> | Failure

Success

Response is returned in the data property.

type Success<TResponse> = { success: true; data: TResponse }

Failure

Errors are returned in the error property.

type Failure = { success: false; error: string }

Contributing

This is a pet project to save me time at work. It is still under development and not ready for use.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Authors

• B Jones RFD - Package Noob - B-Jones-RFD

License

MIT License