b-jones-rfd
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
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 | Required |
|---|---|---|---|
| string | SharePoint domain | sharepoint.domain.com | Y |
serverRelativeUrl
| Type | Description | Example | Required |
|---|---|---|---|
| string | SharePoint site relative Url | /path/to/my/site | Y |
protocol
| Type | Default value | Options | Description | Required |
|---|---|---|---|---|
| string | 'https' | 'http' or 'http' | Site protocol | N |
domain
| Type | Default value | Description | Required |
|---|---|---|---|
| string | '' | NTLM domain | N |
hostname
| Type | Default value | Description | Required |
|---|---|---|---|
| string | os.hostname() | OS Hostname | N |
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 | Default |
|---|---|---|---|---|
| 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 | |
| timeout | number | Request timeout (milliseconds) | N | 0 |
| binary | boolean | Stream response | N | false |
addDocumentToLibrary(options)
options
| Property | Type | Description | Required | Default |
|---|---|---|---|---|
| accessToken | string | SharePoint access token | Y | |
| folder | string | SharePoint folder name | Y | |
| fileName | string | File name | Y | |
| payload | Buffer | File contents | Y | |
| timeout | number | Request timeout (milliseconds) | N | 0 |
| binary | boolean | Stream response | N | false |
addListItem(options)
options
| Property | Type | Description | Required | Default |
|---|---|---|---|---|
| accessToken | string | SharePoint access token | Y | |
| listName | string | SharePoint list name | Y | |
| payload | string | List item JSON as string | Y | |
| timeout | number | Request timeout (milliseconds) | N | 0 |
| binary | boolean | Stream response | N | false |
checkFolderExistsInLibrary(options)
options
| Property | Type | Description | Required | Default |
|---|---|---|---|---|
| folder | string | SharePoint folder/subfolder name | Y | |
| timeout | number | Request timeout (milliseconds) | N | 0 |
| binary | boolean | Stream response | N | false |
createFolderInLibrary(options)
options
| Property | Type | Description | Required | Default |
|---|---|---|---|---|
| accessToken | string | SharePoint access token | Y | |
| folder | string | SharePoint folder/subfolder name | Y | |
| timeout | number | Request timeout (milliseconds) | N | 0 |
| binary | boolean | Stream response | N | false |
deleteDocumentFromLibrary(options)
options
| Property | Type | Description | Required | Default |
|---|---|---|---|---|
| accessToken | string | SharePoint access token | Y | |
| folder | string | SharePoint folder/subfolder name | Y | |
| fileName | string | File name | Y | |
| timeout | number | Request timeout (milliseconds) | N | 0 |
| binary | boolean | Stream response | N | false |
deleteListItem(options)
options
| Property | Type | Description | Required | Default |
|---|---|---|---|---|
| accessToken | string | SharePoint access token | Y | |
| listName | string | SharePoint list name | Y | |
| spId | number | SharePoint list item ID | Y | |
| timeout | number | Request timeout (milliseconds) | N | 0 |
| binary | boolean | Stream response | N | false |
getAuthToken()
options
| Property | Type | Description | Required | Default |
|---|---|---|---|---|
| timeout | number | Request timeout (milliseconds) | N | 0 |
| binary | boolean | Stream response | N | false |
getFormDigestValue()
options
| Property | Type | Description | Required | Default |
|---|---|---|---|---|
| timeout | number | Request timeout (milliseconds) | N | 0 |
| binary | boolean | Stream response | N | false |
getDocumentFromLibrary(options)
options
| Property | Type | Description | Required | Default |
|---|---|---|---|---|
| folder | string | SharePoint folder name | Y | |
| fileName | string | File name | Y | |
| timeout | number | Request timeout (milliseconds) | N | 0 |
| binary | boolean | Stream response | N | true |
getListContents(options)
options
| Property | Type | Description | Required | Default |
|---|---|---|---|---|
| listName | string | SharePoint list name | Y | |
| params | UrlSearchParams | SharePoint list name | N | |
| timeout | number | Request timeout (milliseconds) | N | 0 |
| binary | boolean | Stream response | N | false |
getListItem(options)
options
| Property | Type | Description | Required | Default |
|---|---|---|---|---|
| listName | string | SharePoint list name | Y | |
| spId | number | SharePoint list item ID | Y | |
| timeout | number | Request timeout (milliseconds) | N | 0 |
| binary | boolean | Stream response | N | false |
getListItemType(options)
options
| Property | Type | Description | Required | Default |
|---|---|---|---|---|
| listName | string | SharePoint list name | Y | |
| timeout | number | Request timeout (milliseconds) | N | 0 |
| binary | boolean | Stream response | N | false |
updateListItem(options)
options
| Property | Type | Description | Required | Default |
|---|---|---|---|---|
| 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 | |
| timeout | number | Request timeout (milliseconds) | N | 0 |
| binary | boolean | Stream response | N | false |
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