sap-bo/README.md

# SAP Business One Service Layer Connector

Produkční Node.js + TypeScript connector pro SAP Business One Service Layer REST/OData API. Používá pouze Service Layer (`/b1s/v1`), ne SAP DI API.

Součástí repozitáře je i malý AppFactory HTTP wrapper s endpointy:

- `GET /`
- `GET /health`
- `GET /docs`
- `GET /openapi.json`
- `POST /api/session/login` (vrací i verzi Service Layeru a session timeout)
- `POST /api/session/logout`
- `GET /api/system/info` (verze SAP, dostupné entity sety, UDF/UDT/UDO, admin info)
- `GET /api/<resource>`
- `GET /api/<resource>/all`
- `GET /api/<resource>/{id}`
- `POST /api/<resource>`
- `PATCH /api/<resource>/{id}`
- `DELETE /api/<resource>/{id}` pouze pro obecně mazatelné resource

## Instalace

```bash
npm install
npm run build
npm test
```

## Konfigurace knihovny

Vytvoř `.env` podle `.env.example`:

```env
SAP_B1_BASE_URL=https://sap.example.local:50000
SAP_B1_COMPANY_DB=SBODEMOUS
SAP_B1_USERNAME=manager
SAP_B1_PASSWORD=change-me
SAP_B1_LANGUAGE=
SAP_B1_TIMEOUT_MS=30000
SAP_B1_REJECT_UNAUTHORIZED=true
SAP_B1_RETRY_COUNT=2
SAP_B1_RETRY_DELAY_MS=250
```

`SAP_B1_BASE_URL` může být buď root Service Layer hostu, nebo přímo URL končící `/b1s/v1`. Hesla ani session tokeny se nelogují.

Pro self-signed certifikáty lze v interním prostředí nastavit:

```env
SAP_B1_REJECT_UNAUTHORIZED=false
```

V produkci preferuj důvěryhodný certifikát a ponech `true`.

## HTTP API credentials

Podle AppFactory pravidel se SAP credentials pro HTTP API předávají v request headers, ne v JSON body:

```http
X-SAP-B1-BaseUrl: https://sap.example.local:50000
X-SAP-B1-CompanyDB: SBODEMOUS
X-SAP-B1-Username: manager
X-SAP-B1-Password: <secret>
X-SAP-B1-Language: 3
X-SAP-B1-Reject-Unauthorized: true
X-SAP-B1-Timeout-Ms: 30000
```

Povinné jsou `X-SAP-B1-BaseUrl`, `X-SAP-B1-CompanyDB`, `X-SAP-B1-Username` a `X-SAP-B1-Password`.

Heslo se nesmí zapisovat do README, logů ani běžných response. `/docs` obsahují interaktivní formulář, který tyto hodnoty posílá jako hlavičky.

## Použití

### Login a logout

```ts
import { SapBusinessOneServiceLayer, loadSapB1ConfigFromEnv } from "./src";

const sap = new SapBusinessOneServiceLayer(loadSapB1ConfigFromEnv());

await sap.login();
await sap.logout();
```

Login volá `POST /b1s/v1/Login`, uloží cookies `B1SESSION` a `ROUTEID` a posílá je v dalších requestech. Při expiraci session a odpovědi `401` connector jednou provede re-login a request zopakuje.

### Vypsání Business Partners

```ts
const partners = await sap.businessPartners.list({
  select: ["CardCode", "CardName", "CardType"],
  filter: "CardType eq 'cCustomer'",
  top: 50,
  orderby: "CardName asc"
});

console.log(partners.value);
```

### Načtení všech záznamů přes nextLink

```ts
const allItems = await sap.items.listAll({
  select: ["ItemCode", "ItemName"],
  top: 100
});
```

Connector podporuje starší `odata.nextLink` i novější `@odata.nextLink`.

### Vytvoření objednávky

```ts
const order = await sap.orders.create({
  CardCode: "C001",
  DocDueDate: "2026-07-15",
  DocumentLines: [
    {
      ItemCode: "A00001",
      Quantity: 2,
      UnitPrice: 100
    }
  ]
});
```

### Aktualizace položky

```ts
await sap.items.update("A00001", {
  ItemName: "Updated item name"
});
```

## Resource moduly

Implementované resource moduly:

- `businessPartners`
- `items`
- `orders`
- `invoices`
- `purchaseOrders`
- `deliveryNotes`
- `stockTransfers`

Každý modul má:

- `list(query?)`
- `listAll(query?)`
- `get(id)`
- `create(data)`
- `update(id, data)`
- `delete(id)` pouze tam, kde je povolené mazání

U marketing dokumentů (`Orders`, `Invoices`, `PurchaseOrders`, `DeliveryNotes`) a skladových převodek je delete v connectoru záměrně blokovaný. SAP Business One obvykle řeší rušení dokumentů storno/cancel operacemi podle typu dokladu a nastavení firmy.

## Zpracování chyb

Connector převádí chyby na `SapB1Error`:

- `status` HTTP status
- `code` SAP error code, pokud jej Service Layer vrátí
- `message` bezpečná chybová zpráva
- `retryable` příznak pro dočasné chyby

Retry se používá pro `408`, `429` a `5xx`. Citlivé hodnoty jako heslo, cookies a session tokeny se při logování redigují.

## Testy

Testy používají mockované HTTP odpovědi přes axios adapter nebo fake klienty. Nevolají reálný SAP.

```bash
npm test
```

Pokryté oblasti:

- autentizace a cookies
- logout
- automatický re-login po `401`
- OData query parametry
- resource URL builder

## AppFactory

Aplikace poslouchá na `0.0.0.0` a portu `PORT` s výchozí hodnotou `3000`. `ROOT_PATH` se používá pro dokumentaci a testovací requesty za reverse proxy, například `/apps/sap-bo`.

`/docs` je Swagger UI servírované přímo jako HTML (stejně jako sousední `google-service`),
bez statického middleware – proto nevzniká redirect `/docs` → `/docs/`, který by za proxy
zahodil prefix. Assety se načítají z CDN, spec URL je `ROOT_PATH + /openapi.json`. V Swaggeru
použij `Authorize` pro vyplnění povinných `X-SAP-B1-*` hlaviček a potom `Try it out` u
konkrétní operace. OpenAPI `servers` se nastaví z `ROOT_PATH` (jinak `/`), takže za proxy
volá například `/apps/sap-bo/api/business-partners`, ne root doménu.

## TODO ověřit v konkrétní instalaci SAP Business One

- Přesné enum hodnoty a povinná pole pro jednotlivé entity se mohou lišit podle lokalizace, add-onů a verze SAP Business One.
- U rušení dokladů ověř konkrétní Service Layer akce dostupné pro daný typ dokladu a firemní nastavení.
- U velkých datasetů ověř server-side limity stránkování a maximální povolené `$top`.
- Ověř, zda konkrétní instalace vrací OData metadata ve starším formátu `odata.*` nebo novějším `@odata.*`.