@lindle/sharepoint_requests 0.1.18 → 0.1.20

package/README.md

@@ -1,179 +1,184 @@
 # HTTP SharePoint Requests
 
-This package is a TypeScript library for interacting with SharePoint REST APIs. It provides a structured and flexible approach to perform CRUD operations, handle user information, manage files, and retrieve metadata from SharePoint lists.
+TypeScript knihovna pro práci se SharePoint REST API nad `axios`.
+Primární cíl je jednodušší skládání URL, bezpečnější CRUD a čitelnější API.
 
 ## Installation
 
-Install the package using npm:
-
 ```bash
 npm install @lindle/sharepoint_requests
 ```
 
-## Usage
-
-### Create a SharePoint Request Instance
+## Quick Start
 
-```typescript
+```ts
 import createBase from '@lindle/sharepoint_requests';
 
-const sharepoint = createBase().create({
-  baseURL: 'https://your-sharepoint-site.com',
-});
-```
-
-### Basic Methods
+type Task = {
+  Title: string;
+  Description?: string;
+  CategoryRef?: number;
+};
 
-#### Retrieve List Fields
+type DB = {
+  LISTS: {
+    Tasks: Task;
+  };
+};
 
-```typescript
-const fields = await sharepoint.field('ListName', 'FieldName');
-console.log(fields);
+const sp = createBase<DB>().create({
+  baseURL: 'https://tenant.sharepoint.com/sites/demo',
+});
 ```
 
-#### Access Lists
-
-```typescript
-const lists = await sharepoint.lists().get();
-console.log(lists);
-```
+## API Overview
 
-#### Access Items in a List
+### 1. List scope (`from`) - doporučené
 
-```typescript
-const { data, meta } = await sharepoint.from('ListName').get({ limit: 10 });
-console.log({ data, meta });
-```
+`from(listName)` vrací immutable scope. Každý scope drží vlastní endpoint/context, takže paralelní volání si navzájem nepřepisují stav.
 
-#### Create a New Item in a List
+```ts
+const tasks = sp.from('Tasks');
 
-```typescript
-const newItem = await sharepoint.from('ListName').create({
-  Title: 'New Item',
-  Description: 'This is a new item.',
+const { data, meta } = await tasks.get({
+  cols: ['Title'],
+  limit: 10,
+  orderBy: ['Title', 'asc'],
 });
-console.log(newItem);
+
+console.log(meta.url.toString());
 ```
 
-#### Update an Item in a List
+### 2. CRUD položek
 
-```typescript
-const updatedItem = await sharepoint.from('ListName').update(1, {
-  Title: 'Updated Title',
+```ts
+const tasks = sp.from('Tasks');
+
+await tasks.create({
+  Title: 'Prepare monthly report',
+  Description: 'Draft v1 by Friday',
 });
-console.log(updatedItem);
-```
 
-#### Delete an Item in a List
+await tasks.update(15, {
+  Title: 'Prepare monthly report (final)',
+});
 
-```typescript
-await sharepoint.from('ListName').delete(1);
-console.log('Item deleted successfully');
+await tasks.delete(15);
+// alias:
+await tasks.remove(15);
 ```
 
-### Advanced Features
-
-#### Upload Files
+### 3. Pole (fields) listu
 
-```typescript
-const file = new File(['content'], 'example.txt');
-await sharepoint.from('ListName').createFile({ file, itemId: 1 });
-console.log('File uploaded successfully');
+```ts
+const allFields = await sp.from('Tasks').fields().get();
+const titleField = await sp.from('Tasks').fields({ fieldName: 'Title' }).get();
 
-const doc = new File(['doc content'], 'document.pdf');
-await sharepoint.from('Documents', '2013').uploadFile({ file: doc, folderPath: 'Shared/SubFolder' });
-console.log('Library file uploaded successfully');
-
-await sharepoint.from('Documents').deleteFile({ fileName: 'document.pdf', folderPath: 'Shared/SubFolder' });
-console.log('Library file deleted successfully');
+// shortcut:
+const titleField2 = await sp.field('Tasks', 'Title');
 ```
 
-#### Send Emails
+### 4. Přílohy a soubory
 
-```typescript
-await sharepoint.email(
-  'sender@example.com',
-  ['recipient@example.com'],
-  'Subject of Email',
-  'Body of the email content.'
-);
-console.log('Email sent successfully');
-```
+```ts
+const tasks = sp.from('Tasks');
 
-#### Retrieve Current User Information
+const attachment = new File(['hello'], "O'Brien.txt");
+await tasks.createFile({ file: attachment, itemId: 10 });
 
-```typescript
-const currentUser = await sharepoint.getCurrentUser();
-console.log(currentUser);
-```
+const docs = sp.from('Tasks', '2013');
+const doc = new File(['contract body'], 'contract.pdf');
 
-#### Retrieve User Properties
+await docs.uploadFile({
+  file: doc,
+  folderPath: ['Shared', 'Contracts', '2026'],
+  overwrite: true,
+});
 
-```typescript
-const userProfile = await sharepoint.currentUserProperties();
-console.log(userProfile);
+await docs.deleteFile({
+  fileName: 'contract.pdf',
+  folderPath: ['Shared', 'Contracts', '2026'],
+});
 ```
 
-### Authentication
+`files` namespace alias:
 
-Ensure that the requests are authenticated by passing the appropriate cookies or tokens for your SharePoint environment.
+```ts
+await sp.from('Tasks').files.attach({ file: attachment, itemId: 10 });
+await sp.from('Tasks').files.upload({ file: doc });
+await sp.from('Tasks').files.remove({ fileName: 'contract.pdf' });
+```
 
-### Error Handling
+### 5. Folder endpoint
 
-Handle errors using try-catch blocks:
+```ts
+const folderData = await sp.folder(['Shared Documents', 'Invoices']).get({
+  type: 'Files',
+  cols: ['Name'],
+  limit: 20,
+});
 
-```typescript
-try {
-  const lists = await sharepoint.lists().get();
-  console.log(lists);
-} catch (error) {
-  console.error('An error occurred:', error);
-}
+// default type je Files:
+const folderData2 = await sp.folder('Shared Documents/Invoices').get();
 ```
 
-### TypeScript Support
-
-The package is fully typed, enabling autocompletion and type safety for all methods.
+### 6. Users + Email
 
-## API Reference
+```ts
+const currentUser = await sp.getCurrentUser();
+const profile = await sp.currentUserProperties();
+const permission = await sp.currentUserPermission();
 
-### Constructor
+const siteUsers = await sp.users({ limit: 25 }).get();
+const searchResult = await sp.user.searchUser('john.doe');
+const matchedSiteUsers = await sp.user.searchSiteUser("o'connor");
 
-#### `createBase<T>()`
-
-- Creates a base instance for SharePoint requests.
-- **Params:**
-  - `baseURL` (string): The base URL of your SharePoint site.
+await sp.sendEmail({
+  From: 'sender@company.com',
+  To: ['recipient@company.com'],
+  Subject: 'Build status',
+  Body: 'Deployment completed.',
+});
 
-### Methods
+// kompatibilní shortcut:
+await sp.email(
+  'sender@company.com',
+  ['recipient@company.com'],
+  'Build status',
+  'Deployment completed.'
+);
+```
 
-#### Lists
+## SharePoint Version
 
-- `lists().get()` - Retrieve all lists in the SharePoint site.
-- `from(listName)` - Access specific list operations.
+Default je `2013`.
 
-#### Items
+```ts
+await sp.from('Tasks', '2013').get();
+await sp.from('Tasks', '2010').get();
+```
 
-- `create(data)` - Create a new list item.
-- `get(options)` - Retrieve list items with filters, sorting, and limits.
-- `update(id, data)` - Update an existing list item.
-- `delete(id)` - Delete a list item.
+`list(listName)` je stále dostupné jako deprecated alias na `from(listName, '2010')`.
 
-#### Users
+## Response Shape
 
-- `getCurrentUser()` - Retrieve the current user information.
-- `userGetId(userName)` - Get the ID of a user by username.
+Kolekce vrací:
 
-#### Files
+```ts
+{
+  data: ...,
+  meta: { url: URL }
+}
+```
 
-- `createFile({ file, itemId })` - Upload a file to a list item.
-- `uploadFile({ file, folderPath, overwrite })` - Upload a file to a document library (SharePoint 2013).
-- `deleteFile({ fileName, folderPath })` - Delete a file from a document library (SharePoint 2013).
+To zjednodušuje debug výsledné OData URL.
 
-## Development
+## Notes
 
-Feel free to contribute or report issues. Pull requests are welcome.
+- Knihovna předpokládá, že autentizaci řeší prostředí (cookies/tokeny).
+- Write operace používají `X-RequestDigest`.
+- Názvy listů, fieldů a souborů se interně escapují pro OData string literal.
 
 ## License
 
-MIT License. See [LICENSE](LICENSE) for details.
+MIT (viz `LICENSE`).