@b-jones-rfd/sp-rest-connect - v5.1.1
    Preparing search index...

    Type Alias SiteConnection

    All actions bound to one site. Create with createSiteConnection.

    Write actions need a request digest; the connection obtains, caches and refreshes one automatically. Pass requestDigest yourself only if you want to manage it (see SiteConnection.getFormDigestValue).

    type SiteConnection = {
        addAttachmentToListItem: Action<AddAttachmentToListItemOptions, string>;
        addDocumentToLibrary: Action<AddDocumentToLibraryOptions, string>;
        addListItem: AddListItemAction;
        batch: Action<BatchOptions, BatchResponse[]>;
        checkFolderExistsInLibrary: Action<
            CheckFolderExistsInLibraryOptions,
            boolean,
        >;
        createFolderInLibrary: Action<CreateFolderInLibraryOptions, string>;
        deleteDocumentFromLibrary: Action<DeleteDocumentFromLibraryOptions, string>;
        deleteListItem: Action<DeleteListItemOptions, string>;
        getAllFolderContents: <T = unknown>(
            options: GetAllFolderContentsOptions,
        ) => Promise<Result<T[]>>;
        getAllListContents: <T = unknown>(
            options: GetAllListContentsOptions,
        ) => Promise<Result<T[]>>;
        getAuthToken: Action<RequestOptions, string>;
        getDocumentFromLibrary: Action<GetDocumentFromLibraryOptions, Buffer>;
        getDocumentStreamFromLibrary: Action<
            GetDocumentStreamFromLibraryOptions,
            Readable,
        >;
        getFolderContents: PagedAction<GetFolderContentsOptions>;
        getFormDigestValue: Action<RequestOptions, string>;
        getListContents: PagedAction<GetListContentsOptions>;
        getListItem: TypedAction<GetListItemOptions>;
        getListItemType: Action<GetListItemTypeOptions, string>;
        getNextPage: PagedAction<GetNextPageOptions>;
        iterateFolderContents: PagedIterator<GetAllFolderContentsOptions>;
        iterateListContents: PagedIterator<GetAllListContentsOptions>;
        queryListItems: ItemsAction<QueryListItemsOptions>;
        updateListItem: Action<UpdateListItemOptions, string>;
    }
    Index
    addAttachmentToListItem addDocumentToLibrary addListItem batch checkFolderExistsInLibrary createFolderInLibrary deleteDocumentFromLibrary deleteListItem getAllFolderContents getAllListContents getAuthToken getDocumentFromLibrary getDocumentStreamFromLibrary getFolderContents getFormDigestValue getListContents getListItem getListItemType getNextPage iterateFolderContents iterateListContents queryListItems updateListItem
    addAttachmentToListItem: Action<AddAttachmentToListItemOptions, string>

    Attaches a file to an existing list item.

    POST /_api/web/lists/GetByTitle('{listName}')/items('{spId}')/AttachmentFiles/add(FileName='{fileName}')

    data is the server-relative URL of the new attachment.

    addDocumentToLibrary: Action<AddDocumentToLibraryOptions, string>

    Uploads a file to a document library folder, overwriting any existing file with the same name. payload may be a Buffer or a Readable.

    POST /_api/web/GetFolderByServerRelativeUrl('{serverRelativeUrl}/{folder}')/Files/add(url='{fileName}',overwrite=true)

    data is the server-relative URL of the uploaded file.

    addListItem: AddListItemAction

    Creates a list item.

    POST /_api/web/lists/GetByTitle('{listName}')/items

    data is the created item as SharePoint returned it, typed as T & { Id: number } (unchecked beyond Id).

    const created = await connection.addListItem<Task>({
      listName: 'Tasks',
      payload: { Title: 'Hello' },
    })
    if (created.success) console.log(created.data.Id)
    batch: Action<BatchOptions, BatchResponse[]>

    Sends several REST requests in one round trip.

    POST /_api/$batch

    Requires SharePoint 2016 or later. Each sub-request gets its own BatchResponse; a failing sub-request does not fail the batch, so check ok on each. Consecutive writes are grouped into one changeset (atomic on the server); reads are sent as individual parts.

    data is one response per request, in order.

    const res = await connection.batch({
      requests: [
        { method: 'GET', path: `_api/web/lists/GetByTitle('Tasks')/items?$top=5` },
        { method: 'POST', path: `_api/web/lists/GetByTitle('Tasks')/items`, body: { __metadata: { type }, Title: 'A' } },
        { method: 'MERGE', path: `_api/web/lists/GetByTitle('Tasks')/items(7)`, body: { __metadata: { type }, Title: 'B' } },
      ],
    })
    checkFolderExistsInLibrary: Action<CheckFolderExistsInLibraryOptions, boolean>

    Checks whether a folder exists.

    GET /_api/web/GetFolderByServerRelativeUrl('{serverRelativeUrl}/{folder}')/Exists

    data is true or false. A missing folder is a successful false, not a Failure.

    createFolderInLibrary: Action<CreateFolderInLibraryOptions, string>

    Creates a folder. The parent folder must already exist.

    POST /_api/web/folders

    data is the server-relative URL of the new folder.

    deleteDocumentFromLibrary: Action<DeleteDocumentFromLibraryOptions, string>

    Deletes a file from a document library.

    POST /_api/web/GetFileByServerRelativeUrl('{serverRelativeUrl}/{folder}/{fileName}') with X-HTTP-Method: DELETE

    data is the deleted fileName.

    deleteListItem: Action<DeleteListItemOptions, string>

    Deletes a list item.

    POST /_api/web/lists/GetByTitle('{listName}')/items('{spId}') with X-HTTP-Method: DELETE

    data is an empty string.

    getAllFolderContents: <T = unknown>(
        options: GetAllFolderContentsOptions,
    ) => Promise<Result<T[]>>

    Like SiteConnection.getFolderContents but follows nextLink until every file is collected (or maxPages is reached).

    Type Declaration

    getAllListContents: <T = unknown>(
        options: GetAllListContentsOptions,
    ) => Promise<Result<T[]>>

    Like SiteConnection.getListContents but follows nextLink until every item is collected (or maxPages is reached).

    Type Declaration

    getAuthToken: Action<RequestOptions, string>

    Performs the NTLM handshake against the site and returns the resulting Authorization header value (NTLM Type 3 message).

    This is a low-level diagnostic: NTLM authenticates the TCP connection, not the request, so the value cannot be reused for later requests. Use it to verify credentials, not to obtain a requestDigest — that comes from SiteConnection.getFormDigestValue.

    data is the NTLM <base64> header value.

    getDocumentFromLibrary: Action<GetDocumentFromLibraryOptions, Buffer>

    Downloads a file.

    GET /_api/web/GetFolderByServerRelativeUrl('{serverRelativeUrl}/{folder}')/Files('{fileName}')/$value

    data is the file contents as a Buffer.

    getDocumentStreamFromLibrary: Action<
        GetDocumentStreamFromLibraryOptions,
        Readable,
    >

    Downloads a file as a stream, without buffering it in memory.

    GET /_api/web/GetFolderByServerRelativeUrl('{serverRelativeUrl}/{folder}')/Files('{fileName}')/$value

    data is a Readable of the file contents. HTTP and auth errors are still reported as a Failure before any stream is returned; a network drop mid-download surfaces as an 'error' event on the stream.

    const res = await connection.getDocumentStreamFromLibrary({ folder: 'Shared Documents', fileName: 'big.iso' })
    if (res.success) await pipeline(res.data, createWriteStream('big.iso'))
    getFolderContents: PagedAction<GetFolderContentsOptions>

    Lists the files directly inside a folder (subfolders are not included).

    GET /_api/web/GetFolderByServerRelativeUrl('{serverRelativeUrl}/{folder}')/Files?{params}

    data is the OData value array; each element is a SharePoint SP.File object (Name, ServerRelativeUrl, Length, TimeLastModified, …). nextLink is set when more files remain.

    getFormDigestValue: Action<RequestOptions, string>

    Obtains a request digest, required as requestDigest by every write action.

    POST /_api/contextinfo

    data is the FormDigestValue string. It expires (30 minutes by default); request a new one per batch of writes.

    getListContents: PagedAction<GetListContentsOptions>

    Queries one page of list items.

    GET /_api/web/lists/GetByTitle('{listName}')/items?{params}

    data is the OData value array, typed as T[] (unchecked). nextLink is set when SharePoint has more items than it returned; pass it to SiteConnection.getNextPage, or use SiteConnection.getAllListContents.

    type Task = { Id: number; Title: string }
    const params = new URLSearchParams({ $select: 'Id,Title', $top: '500' })
    const res = await connection.getListContents<Task>({ listName: 'Tasks', params })
    getListItem: TypedAction<GetListItemOptions>

    Reads a single list item by ID.

    GET /_api/web/lists/GetByTitle('{listName}')/items('{spId}')

    data is the item object (odata=nometadata), typed as T (unchecked).

    getListItemType: Action<GetListItemTypeOptions, string>

    Reads the list's entity type name, needed in __metadata.type when creating or updating items.

    GET /_api/web/lists/GetByTitle('{listName}')?$select=ListItemEntityTypeFullName

    data is e.g. 'SP.Data.TasksListItem'.

    getNextPage: PagedAction<GetNextPageOptions>

    Fetches the page a previous result's nextLink points at.

    GET {nextLink}

    The link must be on the connection's own host; anything else is rejected with a Failure so credentials are never sent elsewhere.

    iterateFolderContents: PagedIterator<GetAllFolderContentsOptions>

    Streams folder contents one page at a time. Yields each PageResult; ends after the last page or the first failure.

    for await (const page of connection.iterateFolderContents<SpFile>({ folder: 'Shared Documents' })) {
      if (!page.success) throw new Error(page.error)
      for (const file of page.data) console.log(file.Name)
    }
    iterateListContents: PagedIterator<GetAllListContentsOptions>

    Streams list items one page at a time. Yields each PageResult; ends after the last page or the first failure.

    for await (const page of connection.iterateListContents<Task>({ listName: 'Tasks' })) {
      if (!page.success) throw new Error(page.error)
      for (const task of page.data) console.log(task.Title)
    }
    queryListItems: ItemsAction<QueryListItemsOptions>

    Runs a CAML query against a list.

    POST /_api/web/lists/GetByTitle('{listName}')/GetItems?{params}

    Use this instead of $filter when a list exceeds the 5,000-item view threshold: CAML <Where> clauses on indexed columns are evaluated by SQL Server and are not subject to it. Page with <RowLimit> in the view and pagingInfo built from the last item's Id.

    data is the matching items, typed as T[] (unchecked).

    const open = await connection.queryListItems<Task>({
      listName: 'Tasks',
      viewXml: `<View><Query><Where><Eq><FieldRef Name='Status'/><Value Type='Text'>Open</Value></Eq></Where></Query><RowLimit>500</RowLimit></View>`,
      params: new URLSearchParams({ $select: 'Id,Title' }),
    })
    updateListItem: Action<UpdateListItemOptions, string>

    Partially updates a list item (OData MERGE with If-Match: *, so the last write wins).

    POST /_api/web/lists/GetByTitle('{listName}')/items('{spId}') with X-HTTP-Method: MERGE

    data echoes back the patch string; SharePoint returns no body for a successful MERGE.

    Settings
    Member Visibility

    On This Page
    Properties