npm package: @lindle/sharepoint_requests
Description: 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.
Author: lion.oncemore@gmail.com
Latest version: 0.1.19

# HTTP SharePoint Requests

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

```bash
npm install @lindle/sharepoint_requests
```

## Quick Start

```ts
import createBase from '@lindle/sharepoint_requests';

type Task = {
  Title: string;
  Description?: string;
  CategoryRef?: number;
};

type DB = {
  LISTS: {
    Tasks: Task;
  };
};

const sp = createBase<DB>().create({
  baseURL: 'https://tenant.sharepoint.com/sites/demo',
});
```

## API Overview

### 1. List scope (`from`) - doporučené

`from(listName)` vrací immutable scope. Každý scope drží vlastní endpoint/context, takže paralelní volání si navzájem nepřepisují stav.

```ts
const tasks = sp.from('Tasks');

const { data, meta } = await tasks.get({
  cols: ['Title'],
  limit: 10,
  orderBy: ['Title', 'asc'],
});

console.log(meta.url.toString());
```

### 2. CRUD položek

```ts
const tasks = sp.from('Tasks');

await tasks.create({
  Title: 'Prepare monthly report',
  Description: 'Draft v1 by Friday',
});

await tasks.update(15, {
  Title: 'Prepare monthly report (final)',
});

await tasks.delete(15);
// alias:
await tasks.remove(15);
```

### 3. Pole (fields) listu

```ts
const allFields = await sp.from('Tasks').fields().get();
const titleField = await sp.from('Tasks').fields({ fieldName: 'Title' }).get();

// shortcut:
const titleField2 = await sp.field('Tasks', 'Title');
```

### 4. Přílohy a soubory

```ts
const tasks = sp.from('Tasks');

const attachment = new File(['hello'], "O'Brien.txt");
await tasks.createFile({ file: attachment, itemId: 10 });

const docs = sp.from('Tasks', '2013');
const doc = new File(['contract body'], 'contract.pdf');

await docs.uploadFile({
  file: doc,
  folderPath: ['Shared', 'Contracts', '2026'],
  overwrite: true,
});

await docs.deleteFile({
  fileName: 'contract.pdf',
  folderPath: ['Shared', 'Contracts', '2026'],
});
```

`files` namespace alias:

```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' });
```

### 5. Folder endpoint

```ts
const folderData = await sp.folder(['Shared Documents', 'Invoices']).get({
  type: 'Files',
  cols: ['Name'],
  limit: 20,
});

// default type je Files:
const folderData2 = await sp.folder('Shared Documents/Invoices').get();
```

### 6. Users + Email

```ts
const currentUser = await sp.getCurrentUser();
const profile = await sp.currentUserProperties();
const permission = await sp.currentUserPermission();

const siteUsers = await sp.users({ limit: 25 }).get();
const searchResult = await sp.user.searchUser('john.doe');
const matchedSiteUsers = await sp.user.searchSiteUser("o'connor");

await sp.sendEmail({
  From: 'sender@company.com',
  To: ['recipient@company.com'],
  Subject: 'Build status',
  Body: 'Deployment completed.',
});

// kompatibilní shortcut:
await sp.email(
  'sender@company.com',
  ['recipient@company.com'],
  'Build status',
  'Deployment completed.'
);
```

## SharePoint Version

Default je `2013`.

```ts
await sp.from('Tasks', '2013').get();
await sp.from('Tasks', '2010').get();
```

`list(listName)` je stále dostupné jako deprecated alias na `from(listName, '2010')`.

## Response Shape

Kolekce vrací:

```ts
{
  data: ...,
  meta: { url: URL }
}
```

To zjednodušuje debug výsledné OData URL.

## Notes

- 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 (viz `LICENSE`).