fms-odata-js 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,160 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.0] - 2026-06-23
+
+### Changed — Repository and package rename (`fm-odata-js` → `fms-odata-js`)
+
+The GitHub repository and npm package have been renamed from `fm-odata-js` to `fms-odata-js` to align with the `fms-odata-spec` reference specification and the `@fms-odata/spec-ts` shared types package.
+
+- **Package name:** `fm-odata-js` → `fms-odata-js` on npm. The old package is deprecated and points users to the new name.
+- **Dist bundle filenames:** `fm-odata.esm.js` → `fms-odata.esm.js`, `fm-odata.esm.min.js` → `fms-odata.esm.min.js`, `fm-odata.iife.min.js` → `fms-odata.iife.min.js`.
+- **IIFE global:** `FMODataLib` → `FMSODataLib` (window global for Web Viewer / browser bundles).
+- **Spec dependency:** `@fm-odata/spec-ts` → `@fms-odata/spec-ts` (the spec package was renamed on npm).
+- **Public API class/type identifiers renamed:**
+  - `FMOData` → `FMSOData` (entrypoint class)
+  - `FMODataError` → `FMSODataError` (error class)
+  - `FMODataOptions` → `FMSODataOptions` (constructor options type)
+  - `isFMODataError` → `isFMSODataError` (type guard)
+- **Deprecated aliases.** The old names (`FMOData`, `FMODataError`, `FMODataOptions`, `isFMODataError`) are re-exported as deprecated aliases for backward compatibility. Existing code using named imports keeps working. These aliases will be removed in a future major version.
+
+### Migration
+
+- **npm:** `npm install fms-odata-js` (or update `package.json` dependencies). The old `fm-odata-js` package is deprecated.
+- **Imports:** `import { FMSOData } from 'fms-odata-js'` (new) or `import { FMOData } from 'fms-odata-js'` (deprecated alias, still works).
+- **CDN URLs:** Update `https://cdn.jsdelivr.net/gh/fsans/fm-odata-js@…` to `https://cdn.jsdelivr.net/gh/fsans/fms-odata-js@…` and dist filenames from `fm-odata.esm.min.js` to `fms-odata.esm.min.js`.
+- **IIFE global:** Update `window.FMODataLib` references to `window.FMSODataLib`.
+
+## [0.2.0] - 2026-06-22
+
+### Added — Spec alignment with @fm-odata/spec-ts
+
+This release aligns fm-odata-js with the [fms-odata-spec](https://github.com/fsans/fms-odata-spec) reference specification. The library now depends on `@fm-odata/spec-ts` (as a devDependency — bundled at build time, zero runtime deps) for shared type definitions and the version feature matrix.
+
+- **Version detection & feature gating.** `FMOData#version()` lazily fetches `$metadata`, extracts the `Org.OData.Core.V1.ProductVersion` annotation, and caches the detected FileMaker Server major version (`'19'`, `'21'`, `'22'`, `'26'`, or `'future'`). `FMOData#versionInfo()` returns the full version descriptor with feature flags. `FMOData#hasFeature(feature)` checks if the server supports a specific feature (e.g., `applyAggregation`, `scriptsByFMSID`, `webhooks`). 12 unit tests.
+- **`$apply` aggregation support.** `Query#apply(expr)` sets a raw `$apply` expression. `Query#aggregate(expressions)` builds `aggregate(field with function as alias)`. `Query#groupBy(fields, aggregateExpressions?)` builds `groupby((fields),aggregate(...))`. Requires FMS 2024+ (v22). 7 unit tests.
+- **FMSID-based script invocation.** `FMOData#scriptById(fmsid, opts)` invokes a script by its immutable FMSID via `Script.FMSID:<id>` URL. `ScriptInvoker#runById(fmsid, opts)` and `ScriptInvoker#urlById(fmsid)` provide the low-level API. Requires FMS 2026+ (v26). 7 unit tests.
+- **Record references (`$ref`).** `EntityRef#getRefs(navProperty)`, `addRef(navProperty, relatedKey)`, `setRef(navProperty, relatedKey)`, and `removeRef(navProperty, relatedKey?)` provide full OData `$ref` CRUD for navigation properties. 9 unit tests.
+- **FMID auth support.** `fmidAuth(token)` helper builds an `FMID <token>` Authorization header for FileMaker Cloud. The HTTP client now recognizes the `FMID` auth scheme prefix.
+- **Spec type re-exports.** Version types (`FMVersionMajor`, `FMVersionInfo`, `FMFeatureFlags`, `FMQueryOptionFlags`), auth types (`FMAuthScheme`, `FMAuthToken`, `FMAuthTokenProvider`), aggregate types (`AggregateFunction`), and error types (`ODataErrorBody`) are re-exported from `@fm-odata/spec-ts`.
+- **Error helpers.** `isFMODataError(err)` and `isFMScriptError(err)` type guards.
+- **Standardized env var names.** The test harness and probe script now accept standardized env var names (`FM_SERVER`, `FM_DATABASE`, `FM_USER`, `FM_PASSWORD`, `FM_VERIFY_SSL`, `FM_TIMEOUT`, `FM_LIVE`) alongside the legacy `FM_ODATA_*` names. Standardized names take precedence. `.env.sample` updated with both forms documented.
+
+### Fixed
+
+- **Query parameter encoding now preserves OData-special characters.** `odataEncode()` (used by `buildQueryString`, `Query#toURL()`, and batch operations) keeps commas (`,`), dollar signs (`$`), equals (`=`), and semicolons (`;`) as literal characters instead of percent-encoding them. FileMaker Server rejects `%2C`, `%24`, `%3D`, and `%3B` in `$select`, `$orderby`, `$expand`, and other system query options—now these parameters work correctly with multiple field names and nested expand options (e.g., `$expand=Orders($select=id,total;$top=5)`). (Ported from FMS-ODATA-MCP fix.)
+
+### Added
+
+- M6 — OData `$batch` multipart request/response:
+  - `FMOData#batch()` returns a `Batch` builder for composing multi-operation requests in a single HTTP round-trip.
+  - `Batch#add(op)` queues a read operation (GET entity-set with optional `$top`, `$skip`, `$filter`, `$select`). Returns a `BatchHandle<T>`.
+  - `Batch#changeset(build)` defines an atomic group of write operations (POST / PATCH / DELETE). All operations in a changeset succeed or fail together.
+  - `Changeset#create(entitySet, body)`, `Changeset#patch(entitySet, key, body, opts?)`, `Changeset#delete(entitySet, key, opts?)` add write operations. Each accepts an optional `If-Match` header.
+  - `Batch#send(opts?)` serialises the multipart/mixed body, POSTs to `/<db>/$batch`, and parses the multipart response back into per-operation `BatchOpResult` objects.
+  - `BatchResult` aggregates all responses in request order with an `ok` boolean (true when all statuses < 400).
+  - `BatchHandle<T>` carries a `_promise` that resolves/rejects individually when the batch settles.
+  - Exported types: `Batch`, `Changeset`, `BatchHandle`, `BatchReadOp`, `BatchOpResult`, `BatchResult`.
+  - OData `$`-prefixed query parameters (`$top`, `$filter`, etc.) are serialised without percent-encoding the `$` sign, which is required by FMS.
+  - Multipart MIME parser correctly strips outer `application/http` MIME headers before extracting the inner HTTP status line and body.
+  - 14 unit tests covering serialisation (read, changeset, PATCH/DELETE, string-key escaping), response parsing (single/multi, error, mixed read+changeset), header forwarding, `$batch` URL, and `AbortSignal`.
+  - Live integration test: sends a batch with a read and a single-create changeset, asserts both responses are successful, and cleans up any created rows.
+
+- M5 — OData `$metadata` parser:
+  - `FMOData#metadata(opts?)` fetches and parses the CSDL XML into a typed `ODataMetadata` object.
+  - `FMOData#metadataXml(opts?)` returns the raw XML (escape hatch for debugging).
+  - New exported types: `ODataMetadata`, `EdmEntityType`, `EdmEntitySet`, `EdmProperty`, `EdmAction`.
+  - Metadata results are cached by default; pass `refresh: true` to force a refetch.
+  - Lightweight ~200 LoC XML parser with zero external dependencies (bundle budget ~1 KB gzipped).
+  - 15 unit tests covering entity types, keys, properties, navigation properties, entity sets, and actions.
+  - Live integration test fetches metadata from the configured FMS instance.
+
+## [0.1.5] - 2026-04-29
+
+### Added
+
+- M4 Part 2 — FileMaker container field I/O:
+  - `EntityRef#container(fieldName) → ContainerRef` handle for per-field binary operations.
+  - `ContainerRef.get()` / `getStream()` download via `GET …/<field>/$value` as a `Blob` or `ReadableStream<Uint8Array>` (with parsed `Content-Type`, `size`, and RFC 6266 `filename`).
+  - `ContainerRef.upload(input)` supports two FMS-documented wire formats, selectable via `input.encoding`:
+    - `'binary'` (default): `PATCH …/<field>` with raw bytes plus `Content-Type` and (optionally) `Content-Disposition: inline; filename="…"`. Restricted to PNG, JPEG, GIF, TIFF, and PDF.
+    - `'base64'`: `PATCH …/<EntitySet>(<key>)` with `{ "<field>": "<base64>", "<field>@com.filemaker.odata.ContentType": "…", "<field>@com.filemaker.odata.Filename": "…" }`. Useful for updating multiple containers (or container + regular fields) in one round-trip.
+  - `ContainerRef.delete()` clears the value via `PATCH …/<EntitySet>(<key>)` with `{ "<field>": null }` (no per-field DELETE endpoint exists on FMS).
+  - `ContainerDownload` / `ContainerUploadInput` types exported (`encoding` and `contentType` are optional).
+- `ContainerUploadInput.contentType` is now optional. When omitted, the library sniffs the MIME from the payload's magic bytes (PNG, JPEG, GIF, TIFF, PDF) and rejects unrecognised payloads up-front. New exported helper `sniffContainerMime(bytes)`.
+- `image/tiff` added to `FM_CONTAINER_SUPPORTED_MIME_TYPES`. Round-trips correctly through the OData container endpoints.
+- `EntityRef#fieldValue<V>(fieldName)` — `GET /<EntitySet>(<key>)/<fieldName>` and unwrap the OData `{ value: … }` envelope. Useful for fetching a single scalar column without composing a `$select` query.
+- `keepalive: true` on every fetch for HTTP connection reuse.
+- 35 container unit tests + 16 entity unit tests (was 23 + 13). Coverage includes TIFF acceptance, PNG/PDF magic-byte sniffing on upload, every `sniffContainerMime` branch, and `fieldValue` (basic / percent-encoded field name / null value).
+- Live integration test: uploads a 68-byte PNG fixture (`tests/fixtures/pixel.png`) to a `photo_content` container on a throw-away contact row, reads it back, asserts byte equality, and clears. Soft-skips when the field is missing in the solution.
+- `docs/filemaker-quirks.md`: new sections documenting (a) FMS rejects `PUT` on the OData endpoint and has no per-field DELETE for record data, (b) the `Accept: application/octet-stream` quirk on `$value`, (c) the `Untitled.png` auto-generated filename, and (d) field-tested observations on `/$count` URL FMS vs FMC, `OData-Version` enforcement, `Edm.Stream` vs `Edm.Binary`, and single-quote escaping in keys.
+- `docs/container-download-problem.md`: investigation log for the Accept-header quirk, marked Resolved.
+- `docs/filemaker-odata-container-guide.md`: full Claris OData container-operations reference vendored into the repo.
+
+### Fixed
+
+- **Container downloads now return binary, not the stored filename string.** `ContainerRef.get()` and `getStream()` now send `Accept: */*` (was `application/octet-stream`). FMS 22 returns the field's stored reference value as `text/plain;charset=utf-8` for the `octet-stream` Accept header — every other Accept value returns the actual binary with the correct `Content-Type`. See [`docs/filemaker-quirks.md`](docs/filemaker-quirks.md). The previous "filename causes file reference" hypothesis was a misdiagnosis; filenames round-trip correctly via `Content-Disposition: attachment; filename="…"`.
+- Live integration test for scripts now soft-skips on FMS's actual "Script not found" HTTP response (a plain `FMODataError` with that message), in addition to the originally-anticipated `scriptError: "104"` envelope path.
+
+## [0.1.4] - 2026-04-28
+
+### Added
+
+- M4 Part 1 — FileMaker script execution:
+  - `FMOData#script(name, opts?)`, `Query#script(name, opts?)`, `EntityRef#script(name, opts?)` POST to the FMS `Script.<name>` action endpoint at database, entity-set, or single-record scope.
+  - `ScriptOptions` (`parameter`, `signal`) maps to the FMS `{ "scriptParameter": "..." }` body when provided.
+  - `ScriptResult` envelope (`scriptResult`, `scriptError`, `raw`).
+  - `FMScriptError` (subclass of `FMODataError`) thrown when a script returns a non-zero `scriptError`; HTTP-level failures still surface as plain `FMODataError`.
+  - Public `ScriptInvoker` for advanced callers that need to build invocation paths manually.
+  - 15 new unit tests covering URL construction at all three scopes, parameter encoding, error promotion, envelope unwrapping, 401 retry, and `AbortSignal` propagation.
+  - Optional live integration test: define a `Ping` script in the Contacts demo (or set `FM_ODATA_PING_SCRIPT`) and the live suite will exercise it.
+
+## [0.1.2] - 2026-04-22
+
+### Added
+
+- `examples/webviewer/`: standalone HTML demo for the `Contacts` solution, in two variants:
+  - `index.html` — loads the library from jsDelivr (`/gh/fsans/fm-odata-js@v0.1.1`).
+  - `index-inline.html` — fully inlined bundle; zero runtime network dependencies.
+- `examples/Contacts.fmp12` referenced from the docs as a ready-to-host demo database.
+
+### Changed
+
+- README overhaul: centered hero, badges, feature bullets, status table, production testimonial blockquote, Docs/Contributing/License sections.
+- `examples/consumer-node/README.md`: added a "Test database" section and sanitized placeholder credentials.
+- `LICENSE`: corrected copyright holder name to `Francesc Sans`.
+
+## [0.1.1] - 2026-04-22
+
+### Added
+
+- M1 scaffold: repo layout, TypeScript/Vitest/Playwright/esbuild configs, empty `FMOData` class, placeholder failing unit test.
+- M2 query + URL layer:
+  - `src/url.ts`: `escapeStringLiteral`, `formatDateTime`, `parseDateTime`, `formatLiteral`, `encodePathSegment`, `buildQueryString`.
+  - `src/query.ts`: `Query` fluent builder (`select`, `filter`, `or`, `expand`, `orderby`, `top`, `skip`, `count`, `search`, `toURL`), `Filter` class, `filterFactory`.
+  - `FMOData#from(entitySet)` returns a `Query`.
+  - Public exports: `Query`, `Filter`, `filterFactory`, `FilterFactory`, `FilterInput`, `OrderDir`, `ODataLiteral`.
+  - 62 passing unit tests covering every builder path and URL edge case.
+  - Minified bundle ~4.2 KB raw / ~1.55 KB gzipped.
+- Dev tooling:
+  - `.env.sample` / `.env` for local FMS config; `.env` is git-ignored.
+  - `scripts/env.mjs`, `scripts/insecure-fetch.mjs`, `scripts/probe.mjs`.
+  - `npm run probe` validates connectivity, auth, and the `Contacts` schema against a live FMS.
+  - `FM_ODATA_INSECURE_TLS=1` toggles `NODE_TLS_REJECT_UNAUTHORIZED=0` for dev use with self-signed certs.
+- `docs/filemaker-quirks.md` documenting: Basic-auth-only on OData, `/$count` returning 400, self-signed cert handling.
+- M3 CRUD + auth + errors:
+  - `src/http.ts`: shared request executor — `resolveAuthHeader` (Basic/Bearer auto-detect), `basicAuth(user, pass)` helper, `combineSignals`, `executeRequest`, `executeJson`.
+  - `src/errors.ts`: `parseErrorResponse` handling OData JSON envelope + FileMaker XML envelope.
+  - `src/entity.ts`: `EntityRef` with `.get()`, `.patch()` (with `ifMatch`, `returnRepresentation`), `.delete()`.
+  - `Query#create()` (POST), `Query#get()` returning `{ value, count?, nextLink? }`, `Query#byKey(key)` returning `EntityRef`.
+  - `FMOData#request()` / `FMOData#rawRequest()` low-level escape hatches.
+  - 401 retry via `onUnauthorized` (once), `AbortSignal` + `timeoutMs` composition.
+  - 100 passing unit tests (mocked fetch); 3 passing live-integration tests against the `Contacts` DB covering read, full CRUD round-trip, and error handling.
+  - Opt-in live suite: `FM_ODATA_LIVE=1 npm test -- tests/integration`.
+  - Bundle now ~8.8 KB raw / ~3.2 KB gzipped.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Francesc Sans, nBCN Software, Barcelona
+http://www.ntwk.es — tecnic.at.ntwk.es
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,381 @@
+<div align="center">
+
+# fms-odata-js
+
+**A tiny, type-safe OData v4 client built for FileMaker Server.**
+
+Zero runtime dependencies · ~9.1 KB gzipped · ESM + IIFE · Web Viewer / Browser / Node 18+
+
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-3178c6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![OData](https://img.shields.io/badge/OData-v4-0078D4?logo=data&logoColor=white)](https://www.odata.org/)
+[![FileMaker](https://img.shields.io/badge/FileMaker-19.0--26.0-FF6B00?logo=filemaker&logoColor=white)](https://www.claris.com/filemaker/)
+[![Bundle](https://img.shields.io/badge/gzip-~9.1%20KB-brightgreen)](#)
+[![Deps](https://img.shields.io/badge/runtime%20deps-0-blue)](#)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white)](#)
+[![License](https://img.shields.io/badge/license-MIT-black)](./LICENSE)
+
+</div>
+
+---
+
+## Why fms-odata-js?
+
+FileMaker Server speaks OData v4, but the spec has sharp corners and FMS has quirks. `fms-odata-js` smooths both — so you can forget about URL-encoding `$filter` predicates and focus on your data.
+
+> **Battle-tested in production.** I've been using this library heavily to let FileMaker Web Viewer instances talk to the *same* hosted database they live in — and the performance has been genuinely impressive. Queries that used to require round-tripping through scripts and set-field loops now resolve in a single OData call, with noticeably lower latency and a much cleaner code path. If you're building rich Web Viewer UIs backed by FMS, this is the fastest route I've found.
+
+- **Tiny.** ESM and IIFE bundles, zero runtime dependencies, ~9.1 KB gzipped.
+- **Type-safe.** Fluent, chainable query builder with full TS inference.
+- **Runs anywhere.** Drop it into a FileMaker Web Viewer, a browser, or Node 18+.
+- **FMS-aware.** Handles the documented FMS OData deviations for you.
+- **Version-aware.** Detects the FileMaker Server major version (19, 21, 22, 26) from `$metadata` and gates features accordingly.
+- **Scripts built in.** Invoke FileMaker scripts at database, entity-set, or record scope — by name or by immutable FMSID (v26+).
+- **Containers built in.** Upload, download, stream, or clear container fields with typed helpers — `Blob`, `ArrayBuffer`, and `Uint8Array` all accepted.
+- **Aggregations.** `$apply` builder for `aggregate()` and `groupBy()` — server-side sum, average, min, max, count (FMS 2024+).
+- **Navigation properties.** Full `$ref` CRUD — `getRefs`, `addRef`, `setRef`, `removeRef` for OData relationship links.
+- **Schema introspection.** `$metadata` parsed into typed `ODataMetadata` with entity types, keys, properties, and actions. Cached by default.
+- **Batch requests.** `$batch` builder composes multiple reads and atomic changesets (POST / PATCH / DELETE) into a single HTTP round-trip.
+- **Multi-auth.** Basic, Bearer, and FMID (FileMaker Cloud / Claris ID) auth with 401 retry, `AbortSignal`, and timeouts built in.
+- **Honest errors.** Every failure becomes a normalized `FMSODataError` (or `FMScriptError` for script failures) with `isFMSODataError` / `isFMScriptError` type guards.
+
+## Status
+
+| Milestone   | Scope                                                             | State |
+| ----------- | ----------------------------------------------------------------- | :---: |
+| **M1–M3**   | Query builder · collection GET · single-entity CRUD · auth · errors | Done |
+| **M4 · 1/4**| Script execution (database / entity-set / record scope)            | Done (v0.1.4) |
+| **M4 · 2/4**| Containers (binary upload / download / stream)                     | Done (v0.1.5) |
+| **M5**      | `$metadata` (schema introspection)                                 | Done |
+| **M6**      | `$batch` (multipart with changesets)                               | Done |
+| **v0.2.0**  | Spec alignment — version detection, `$apply`, FMSID scripts, `$ref`, FMID auth, IIFE build | Done (v0.2.0) |
+
+Full roadmap and changes live in [`CHANGELOG.md`](./CHANGELOG.md).
+
+## Install
+
+> **Not yet published to npm.** Until the first release hits the registry, install directly from GitHub or a local checkout.
+
+From GitHub:
+
+```bash
+npm install github:fsans/fms-odata-js
+```
+
+From a local clone:
+
+```bash
+npm install /path/to/fms-odata-js
+```
+
+Once published, the canonical install will be:
+
+```bash
+npm install fms-odata-js
+```
+
+Local dev:
+
+```bash
+npm install
+npm test          # 227 unit tests, offline
+```
+
+## Quick start
+
+```ts
+import { FMSOData, basicAuth } from 'fms-odata-js'
+
+const db = new FMSOData({
+  host: 'https://fms.example.com',
+  database: 'Contacts',
+  token: basicAuth('admin', 'secret'), // FMS OData requires Basic auth
+  timeoutMs: 15_000,
+})
+
+// For FileMaker Cloud, use FMID auth instead:
+// import { fmidAuth } from 'fms-odata-js'
+// token: fmidAuth(clarisIdToken)
+
+// Collection read
+const { value, count } = await db
+  .from('contact')
+  .select('id', 'first_name', 'last_name')
+  .filter((f) => f.eq('last_name', 'Smith'))
+  .orderby('last_name')
+  .top(50)
+  .count()
+  .get()
+
+// Create
+const created = await db.from('contact').create({
+  first_name: 'Alice',
+  last_name: 'Liddell',
+})
+
+// Read / update / delete a single row
+const row = await db.from('contact').byKey(created.id).get()
+await db.from('contact').byKey(row.id).patch({ first_name: 'A.' })
+await db.from('contact').byKey(row.id).delete()
+```
+
+## FileMaker scripts
+
+Invoke FMS-side FileMaker scripts at three scopes. The optional `parameter`
+becomes `Get(ScriptParameter)` inside the script; the script's text result is
+returned as `scriptResult`.
+
+```ts
+// Database scope
+const { scriptResult } = await db.script('Ping', { parameter: 'hello' })
+
+// Entity-set scope (script runs with the table as context)
+await db.from('contact').script('RebuildIndex')
+
+// Single-record scope (script's current record is set to this row)
+await db.from('contact').byKey(42).script('Archive')
+```
+
+A non-zero `scriptError` becomes an `FMScriptError` (subclass of
+`FMSODataError`), so existing error handlers keep working:
+
+```ts
+import { FMScriptError } from 'fms-odata-js'
+
+try {
+  await db.script('Risky')
+} catch (err) {
+  if (err instanceof FMScriptError) {
+    console.error(`FM script error ${err.scriptError}: ${err.scriptResult}`)
+  } else {
+    throw err
+  }
+}
+```
+
+### FMSID-based invocation (v26+)
+
+On FileMaker Server 2026+, scripts can be invoked by their immutable FMSID
+instead of name. This survives script renames and database migrations:
+
+```ts
+const result = await db.scriptById(42, { parameter: 'hello' })
+```
+
+Use `await db.hasFeature('scriptsByFMSID')` to check before calling.
+
+## Container fields
+
+Container fields expose their bytes through `EntityRef#container(fieldName)`.
+The handle gives you three I/O shapes plus a clear operation:
+
+```ts
+const photo = db.from('contact').byKey(42).container('photo')
+
+// Upload (default: binary mode — image / PDF only per FMS)
+await photo.upload({
+  data: new Uint8Array(await file.arrayBuffer()),
+  contentType: 'image/png',
+  filename: 'profile.png',
+})
+
+// Upload any file type (zip, docx, …) via base64 encoding
+await photo.upload({
+  data: zipBytes,
+  contentType: 'application/zip',
+  filename: 'archive.zip',
+  encoding: 'base64',
+})
+
+// Download into memory (good for thumbnails, small assets)
+const { blob, contentType, filename, size } = await photo.get()
+
+// Or stream it (good for large files — no buffering)
+const stream = await photo.getStream()
+await stream.pipeTo(someWritable)
+
+// Clear the container
+await photo.delete()
+```
+
+Under the hood the library uses the two FMS-documented wire formats:
+binary mode `PATCH`es `…/<field>` with raw bytes; base64 mode `PATCH`es the
+parent record with `<field>@com.filemaker.odata.ContentType` /
+`…Filename` annotations. `delete()` clears the value via `PATCH` with
+`{ <field>: null }` (FMS has no per-field DELETE for record data).
+
+The `Content-Disposition` filename is parsed for you on download, including
+RFC 5987 `filename*=UTF-8''…` for non-ASCII names. On upload, non-ASCII
+filenames are emitted in both plain and RFC 5987 form automatically.
+
+## Schema introspection (`$metadata`)
+
+Fetch and inspect the OData CSDL schema emitted by FileMaker Server:
+
+```ts
+const meta = await db.metadata()
+
+console.log(meta.namespace)       // e.g. "FileMaker"
+console.log(meta.entitySets)      // [{ name: "contact", entityType: "FileMaker.contact" }, …]
+console.log(meta.entityTypes)     // [{ name: "contact", keys: ["id"], properties: […] }, …]
+console.log(meta.actions)         // FileMaker scripts exposed as OData Actions
+```
+
+Results are cached by default. Pass `refresh: true` to force a refetch:
+
+```ts
+const fresh = await db.metadata({ refresh: true })
+```
+
+Use `metadataXml()` to get the raw CSDL XML for debugging or forward-compat parsing:
+
+```ts
+const xml = await db.metadataXml()
+```
+
+## Batch requests (`$batch`)
+
+Send multiple operations in a single HTTP round-trip. Reads and atomic changesets
+can be freely mixed:
+
+```ts
+const batch = db.batch()
+
+// Queue a read (GET)
+const contactsHandle = batch.add({
+  op: 'list',
+  entitySet: 'contact',
+  query: { $top: 10, $filter: "status eq 'active'" },
+})
+
+// Queue an atomic write group — all succeed or all fail together
+batch.changeset(cs => {
+  cs.create('contact', { first_name: 'Alice', last_name: 'Liddell' })
+  cs.patch('contact', 42, { status: 'archived' })
+  cs.delete('invoice', 99)
+})
+
+const result = await batch.send()
+
+if (result.ok) {
+  console.log('All operations succeeded')
+}
+
+// Per-operation status and body are in result.responses (in request order)
+for (const r of result.responses) {
+  console.log(r.status, r.ok, r.body)
+}
+```
+
+Changeset operations also expose `If-Match` for optimistic concurrency:
+
+```ts
+batch.changeset(cs => {
+  cs.patch('contact', 42, { status: 'closed' }, { ifMatch: '"abc123"' })
+})
+```
+
+## Version detection & feature gating
+
+The library detects the FileMaker Server major version from the
+`Org.OData.Core.V1.ProductVersion` annotation in `$metadata` and caches it
+for the lifetime of the `FMSOData` instance:
+
+```ts
+const v = await db.version()        // '19' | '21' | '22' | '26' | 'future' | null
+const info = await db.versionInfo() // full descriptor with feature flags
+const ok = await db.hasFeature('applyAggregation') // boolean
+```
+
+Feature flags include `applyAggregation`, `scriptsByFMSID`, `webhooks`, and
+more — see `FMFeatureFlags` in the type exports. This lets you write
+conditional code that adapts to the server's capabilities at runtime.
+
+## Aggregation (`$apply`)
+
+Server-side aggregation via OData `$apply` — requires FileMaker Server 2024+
+(v22). Use `hasFeature('applyAggregation')` to check before calling.
+
+```ts
+// Aggregate: sum, average, min, max, countdistinct
+const { value } = await db
+  .from('orders')
+  .aggregate([{ field: 'total', function: 'sum', alias: 'totalSum' }])
+  .get()
+// $apply=aggregate(total with sum as totalSum)
+
+// Group by with aggregation
+const { value } = await db
+  .from('orders')
+  .groupBy(['customerId'], [
+    { field: 'total', function: 'sum', alias: 'totalSum' },
+    { field: 'total', function: 'average', alias: 'avgTotal' },
+  ])
+  .get()
+// $apply=groupby((customerId),aggregate(total with sum as totalSum,total with average as avgTotal))
+
+// Raw $apply for advanced transformations
+const { value } = await db.from('orders').apply('aggregate(total with max as maxTotal)').get()
+```
+
+## Navigation properties (`$ref`)
+
+Manage OData relationship links between entities via `$ref`:
+
+```ts
+// List related references
+const refs = await db.from('contact').byKey(7).getRefs('addresses')
+// [{ '@odata.id': 'https://fms.example.com/fmi/odata/v4/DB/address(1)' }, ...]
+
+// Add a reference (POST — for collection-valued navigation properties)
+await db.from('contact').byKey(7).addRef('addresses', 42)
+
+// Set a reference (PATCH — for single-valued navigation properties)
+await db.from('order').byKey(100).setRef('customer', 7)
+
+// Remove a reference
+await db.from('contact').byKey(7).removeRef('addresses', 42)
+await db.from('order').byKey(100).removeRef('customer') // clears single-valued
+```
+
+## Live integration tests
+
+Copy `.env.sample` to `.env` and fill in real FMS credentials:
+
+```bash
+npm run probe                                  # quick connectivity check
+FM_LIVE=1 npm test -- tests/integration        # full CRUD against real FMS
+```
+
+> Using self-signed certs on a LAN box? Set `FM_VERIFY_SSL=0` in `.env`.
+>
+> Standardized env var names (`FM_SERVER`, `FM_DATABASE`, `FM_USER`,
+> `FM_PASSWORD`, `FM_VERIFY_SSL`, `FM_TIMEOUT`, `FM_LIVE`) are preferred.
+> Legacy `FM_ODATA_*` names are still accepted as fallbacks.
+
+## Docs
+
+- [`docs/README.md`](./docs/README.md) — API reference and deeper guides
+- [`docs/filemaker-quirks.md`](./docs/filemaker-quirks.md) — FMS OData deviations and how this library works around them
+- [`docs/filemaker-odata-container-guide.md`](./docs/filemaker-odata-container-guide.md) — full Claris OData container-operations reference
+- [`CHANGELOG.md`](./CHANGELOG.md) — full release history
+- [fms-odata-spec](https://github.com/fsans/fms-odata-spec) — reference specification this library aligns to
+- [`examples/`](./examples) — runnable sample projects
+  - [`consumer-node/`](./examples/consumer-node) — Node CLI consuming the library
+  - [`webviewer/`](./examples/webviewer) — **standalone HTML page** ready to drop into a FileMaker Web Viewer (uses the IIFE bundle)
+- [`examples/Contacts.fmp12`](./examples/Contacts.fmp12) — ready-to-host FileMaker test database matching the examples. **Credentials: `admin` / `admin`** (dev use only — change before exposing to any network).
+
+### Build formats
+
+The library ships three bundle formats:
+
+- **ESM** (`dist/fms-odata.esm.js`) — for Node, bundlers, and modern browsers
+- **ESM minified** (`dist/fms-odata.esm.min.js`) — ~9.1 KB gzipped, production use
+- **IIFE** (`dist/fms-odata.iife.min.js`) — global `FMSODataLib`, for FileMaker Web Viewer and `<script>` tag inclusion without a bundler
+
+## Contributing
+
+Issues and PRs are welcome. Please run `npm test` and `npm run typecheck` before opening a PR.
+
+## License
+
+[MIT](./LICENSE) © 2026 Francesc Sans, nBCN Software, Barcelona — <http://www.ntwk.es>