Skip to content

README.md

Latest commit

 

History

History
173 lines (125 loc) · 4.2 KB

README.md

File metadata and controls

173 lines (125 loc) · 4.2 KB

🧩 sharepoint-client-api

A fluent TypeScript/JavaScript wrapper for interacting with SharePoint sites and admin APIs.
Provides a simple, type-safe interface for queries, CRUD operations, and more.

npm version npm downloads License: MIT TypeScript Bundle Size

✨ Features

  • 🧠 Fluent interface for building SharePoint API requests
  • 🌐 Supports site and admin endpoints
  • 🔍 Query builders: select, filter, expand, orderBy, top, skip
  • 🔧 Full CRUD support: get, post, put, patch, delete
  • 🧾 Binary & text responses via setResponseType()
  • 🚫 Optional error ignoring with .ignore()
  • 🔐 Easy token-based authentication

📦 Installation

npm install sharepoint-client-api
# or
yarn add sharepoint-client-api

🚀 Usage

Connect with Azure AD app credentials

import { connectWithSharePoint } from "sharepoint-client-api";

const sp = await connectWithSharePoint({
  siteHostname: "mytenant.sharepoint.com",
  tenantId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  refreshToken: "YOUR_REFRESH_TOKEN",
  appCredentials: {
    clientId: "YOUR_CLIENT_ID",
    clientSecret: "YOUR_CLIENT_SECRET"
  }
});

// Get lists from a specific site
const lists = await sp
  .api("mysite", "lists")
  .select(["Id", "Title"])
  .filter("Title eq 'Documents'")
  .get();

console.log(lists);

🛠 Using admin endpoints

const adminSites = await sp
  .adminApi("/Sites('xxxx')")
  .top(5)
  .get();

console.log(adminSites);

⚙️ Ignoring errors

const result = await sp
  .api("mysite", "lists")
  .ignore()
  .get(); // Returns null if API fails instead of throwing

📨 Setting custom headers

await sp
  .api("mysite", "lists")
  .setHeaders({ "X-Custom-Header": "value" })
  .get();

🧾 Setting response type

await sp
  .api("mysite", "lists")
  .setResponseType("arraybuffer") // useful for file/binary downloads
  .get();

Supported response types include:

  • "json"
  • "text"
  • "arraybuffer"
  • "blob"
  • "stream"
  • "document"

Useful for:

✔ file exports ✔ binary data ✔ text-only responses ✔ streaming content

🧱 Query Builder Methods

Method Description
select(fields) Choose specific fields
filter(condition) OData filter condition
expand(fields) Expand related entities
orderBy(field, ascending?) Sort results
top(count) Limit number of results
skip(count) Skip results
rawQuery(params) Add custom query params
setHeaders(headers) Attach HTTP headers
setResponseType(type) Configure Axios response type

🔄 HTTP Methods

Method Description
get() Perform GET request
post(data) Perform POST request
put(data) Perform PUT request
patch(data) Perform PATCH request
delete() Perform DELETE request

📝 Notes

  • Ensure .api() or .adminApi() is called before making any request.
  • .ignore() allows safe API calls without throwing errors.
  • Supports full OData query syntax for SharePoint.
  • Supports binary and streaming responses via setResponseType().

📜 License

This project is licensed under the MIT License.

⭐ If you find this package helpful, consider giving it a star on GitHub !