Home

Awesome

SPPull - simple client to pull and download files from SharePoint

NPM

npm version Downloads Build Status Gitter

Node.js module for downloading files from SharePoint document libraries.

New in version 2.7.0

import SPPull from 'sppull';
const sppull = SPPull.download; // <-- this is an entry point

New in version 2.2.0

Files streaming download:

New in version 2.1.0

Performance in SPO and HTTPS environments is improved. Download on multiple objects is x2 faster now!

New in version 2.0.6

Smart re-download mechanism. Existing files with no changes are ignored from the download.

Supported SharePoint versions

How to use

Install

npm install sppull --save-dev

Demo

How it works

Usage

const { SPPull } = require('sppull');

const context = {/*...*/};
const options = {/*...*/};

SPPull.download(context, options)
  .then(successHandler)
  .catch(errorHandler);

Arguments

Context

Additional authentication options:

Since communication module (sp-request), which is used in sppull, had received additional SharePoint authentication methods, they are also supported in sppull.

For more information please check node-sp-auth credential options and wiki pages.

Options

Overloads / cases

Use case scenarios can be found on the Scenarios page. This page suggests combinations of options which are optimal for certain use cases.

successHandler

Callback gets called upon successful files download.

errorHandler

Callback gets executed in case of exception inside sppull. Accepts error object as first argument for callback.

Samples

Refer to the Scenarios page for suggested options combinations available with sppull.

Basic usage

TypeSctipt:

import { AuthConfig as SPAuthConfigurator } from 'node-sp-auth-config';
import SPPull, { ISPPullOptions, ISPPullContext } from 'sppull';

new SPAuthConfigurator().getContext().then(({ siteUrl, authOptions }) => {

  const context: ISPPullContext = {
    siteUrl: context.siteUrl,
    ...context.authOptions
  } as any;

  const options: ISPPullOptions = {
    spRootFolder: 'Shared%20Documents',
    dlRootFolder: './Downloads/Documents'
  };

  SPPull.download(context, options);

}).catch(console.log);

or ES6:

const { SPPull } = require('sppull');

const context = {
  siteUrl: "http://contoso.sharepoint.com/subsite",
  creds: {
    username: "user@contoso.com",
    password: "_Password_",
    online: true
  }
};

const options = {
  spRootFolder: "Shared%20Documents/Contracts",
  dlRootFolder: "./Downloads/Contracts"
};

/*
 * All files will be downloaded from http://contoso.sharepoint.com/subsite/Shared%20Documents/Contracts folder
 * to __dirname + /Downloads/Contracts folder.
 * Folders structure will remain original as it is in SharePoint's target folder.
*/
SPPull.download(context, options)
  .then((downloadResults) => {
    console.log("Files are downloaded");
    console.log("For more, please check the results", JSON.stringify(downloadResults));
  })
  .catch((err) => {
    console.log("Core error has happened", err);
  });

Passwords storage

To eliminate any local password storing if preferable to use any two-way hashing technique, like cpass.

Inspiration and references

This project was inspired by spsave by Sergei Sergeev and gulp-spsync by Wictor Wilén projects.

SPPull depends heavily on sp-request module and use it to send REST queries to SharePoint.