fms-odata-js 0.3.0

package/dist/batch.d.ts

@@ -0,0 +1,154 @@
+/**
+ * $batch multipart composer and response parser (M6).
+ *
+ * OData $batch allows multiple operations in a single HTTP round-trip.
+ * A batch consists of:
+ *   - Read operations (GET) at the top level
+ *   - Changesets (atomic groups of writes: POST, PATCH, DELETE)
+ *
+ * FMS endpoint: POST /fmi/odata/v4/{db}/$batch
+ * Content-Type: multipart/mixed; boundary=batch_<uuid>
+ *
+ * The implementation generates unique boundaries using crypto.randomUUID()
+ * (available in Node 18+ and modern browsers), composes the multipart
+ * body, and parses the multipart response back into per-operation results.
+ *
+ * ⚠️  KNOWN FMS LIMITATIONS (pending investigation — tested against FMS 21.x):
+ *
+ * 1. GET operations must NOT appear before a changeset.
+ *    Placing a read op before a changeset causes FMS to return HTTP 400:
+ *    "Expected batch boundary at 'Content-Type: applic...'".
+ *    FMS's parser appears to misread the changeset's nested boundary as a
+ *    batch-level boundary when GETs precede it.
+ *    → Workaround: always add changesets before reads in the batch.
+ *
+ * 2. Multiple consecutive GET operations return only one fewer response than
+ *    expected — the last GET in a sequence is silently dropped by FMS.
+ *    E.g. three GETs → only two responses.
+ *    → Workaround: limit batches to one read op at the end, or accept the loss.
+ *
+ * 3. POST/PATCH within a changeset requires an explicit Content-Length header
+ *    on the inner HTTP request (FMS cannot determine body length from multipart
+ *    structure alone). This is handled by utf8ByteLength() during serialisation.
+ *
+ * These constraints differ from the OData 4.01 spec and the official Claris
+ * documentation examples. They were discovered empirically. Batch support in
+ * this library is functional but limited to: changeset (optional) followed by
+ * at most one read operation per batch call.
+ */
+import type { FMSOData } from './client.js';
+import type { ODataLiteral } from './url.js';
+import type { RequestOptions } from './types.js';
+/** Handle returned when adding an operation to a batch. Resolves to the operation result. */
+export interface BatchHandle<T> {
+    readonly __brand: 'BatchHandle';
+    /** @internal */ readonly _promise: Promise<T>;
+    /** @internal */ readonly _index: number;
+}
+/** Input for a read operation (GET) in a batch. */
+export interface BatchReadOp {
+    /** Entity set name (layout/table). */
+    entitySet: string;
+    /** Operation type. */
+    op: 'list';
+    /** Query options: $top, $skip, $filter, etc. */
+    query?: {
+        $top?: number;
+        $skip?: number;
+        $filter?: string;
+        $select?: string;
+    };
+}
+/** Result of a batch operation. */
+export interface BatchOpResult<T = unknown> {
+    status: number;
+    body?: T;
+    headers: Headers;
+    ok: boolean;
+}
+/** Result of executing a batch. */
+export interface BatchResult {
+    /** All responses in request order. */
+    responses: BatchOpResult[];
+    /** True if all responses have status < 400. */
+    ok: boolean;
+}
+/** Represents an operation within a changeset. */
+interface ChangesetOp {
+    method: string;
+    path: string;
+    headers?: Record<string, string>;
+    body?: string;
+}
+/** Changeset builder for atomic write operations. */
+export declare class Changeset {
+    private _ops;
+    private _handles;
+    private _baseUrl;
+    constructor(baseUrl: string);
+    /** @internal */
+    get _operations(): ChangesetOp[];
+    /** @internal */
+    get _handleSlots(): Array<{
+        resolve: (v: unknown) => void;
+        reject: (e: unknown) => void;
+    }>;
+    /**
+     * Create a new entity within this changeset.
+     */
+    create<T = unknown>(entitySet: string, body: Record<string, unknown>): BatchHandle<T>;
+    /**
+     * Patch an existing entity within this changeset.
+     */
+    patch<T = unknown>(entitySet: string, key: ODataLiteral, body: Record<string, unknown>, opts?: {
+        ifMatch?: string;
+    }): BatchHandle<T>;
+    /**
+     * Delete an entity within this changeset.
+     */
+    delete(entitySet: string, key: ODataLiteral, opts?: {
+        ifMatch?: string;
+    }): BatchHandle<void>;
+}
+/** Batch builder for composing multipart/mixed requests. */
+export declare class Batch {
+    private _client;
+    private _parts;
+    private _changesets;
+    constructor(client: FMSOData);
+    /**
+     * Add a read operation (GET) to the batch.
+     * Read operations are not part of a changeset and execute independently.
+     */
+    add<T = unknown>(op: BatchReadOp): BatchHandle<T>;
+    /**
+     * Create an atomic changeset (group of write operations).
+     * All operations in a changeset succeed or fail together.
+     */
+    changeset(build: (cs: Changeset) => void): void;
+    /**
+     * Serialize the batch into a multipart/mixed body.
+     * @internal
+     */
+    _serialize(): {
+        boundary: string;
+        body: string;
+    };
+    /**
+     * Send the batch request and parse the multipart response.
+     */
+    send(opts?: RequestOptions): Promise<BatchResult>;
+    /**
+     * Parse a multipart/mixed batch response.
+     * @internal
+     */
+    _parseResponse(responseText: string, contentType: string): BatchResult;
+    /** @internal — parse a single HTTP response part. */
+    private _parseHttpPart;
+    /** @internal — parse a changeset multipart response. */
+    private _parseChangesetResponse;
+    /** @internal — resolve a batch handle with the result. */
+    private _resolveHandle;
+}
+export {};
+//# sourceMappingURL=batch.d.ts.map

package/dist/batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch.d.ts","sourceRoot":"","sources":["../src/batch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AAE3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAE5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD,6FAA6F;AAC7F,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAA;IAC/B,gBAAgB,CAAC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;IAC9C,gBAAgB,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACzC;AAED,mDAAmD;AACnD,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAA;IACjB,sBAAsB;IACtB,EAAE,EAAE,MAAM,CAAA;IACV,gDAAgD;IAChD,KAAK,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAC9E;AAED,mCAAmC;AACnC,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACxC,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,CAAC,CAAA;IACR,OAAO,EAAE,OAAO,CAAA;IAChB,EAAE,EAAE,OAAO,CAAA;CACZ;AAED,mCAAmC;AACnC,MAAM,WAAW,WAAW;IAC1B,sCAAsC;IACtC,SAAS,EAAE,aAAa,EAAE,CAAA;IAC1B,+CAA+C;IAC/C,EAAE,EAAE,OAAO,CAAA;CACZ;AAoDD,kDAAkD;AAClD,UAAU,WAAW;IACnB,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,qDAAqD;AACrD,qBAAa,SAAS;IACpB,OAAO,CAAC,IAAI,CAAoB;IAChC,OAAO,CAAC,QAAQ,CAA6E;IAC7F,OAAO,CAAC,QAAQ,CAAQ;gBAEZ,OAAO,EAAE,MAAM;IAI3B,gBAAgB;IAChB,IAAI,WAAW,IAAI,WAAW,EAAE,CAE/B;IAED,gBAAgB;IAChB,IAAI,YAAY,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;QAAC,MAAM,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAA;KAAE,CAAC,CAEzF;IAED;;OAEG;IACH,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC;IAmBrF;;OAEG;IACH,KAAK,CAAC,CAAC,GAAG,OAAO,EACf,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAC1B,WAAW,CAAC,CAAC,CAAC;IAqBjB;;OAEG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,WAAW,CAAC,IAAI,CAAC;CAe7F;AAUD,4DAA4D;AAC5D,qBAAa,KAAK;IAChB,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,MAAM,CAAkB;IAChC,OAAO,CAAC,WAAW,CAAkB;gBAEzB,MAAM,EAAE,QAAQ;IAI5B;;;OAGG;IACH,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,EAAE,EAAE,WAAW,GAAG,WAAW,CAAC,CAAC,CAAC;IAiBjD;;;OAGG;IACH,SAAS,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,SAAS,KAAK,IAAI,GAAG,IAAI;IAQ/C;;;OAGG;IACH,UAAU,IAAI;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE;IA4ChD;;OAEG;IACG,IAAI,CAAC,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,WAAW,CAAC;IAqB3D;;;OAGG;IACH,cAAc,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,WAAW;IAuDtE,qDAAqD;IACrD,OAAO,CAAC,cAAc;IAsCtB,wDAAwD;IACxD,OAAO,CAAC,uBAAuB;IAsB/B,0DAA0D;IAC1D,OAAO,CAAC,cAAc;CAIvB"}

package/dist/client.d.ts

@@ -0,0 +1,160 @@
+import { Batch } from './batch.js';
+import { type HttpClientContext, type HttpRequestOptions } from './http.js';
+import { type MetadataOptions, type ODataMetadata } from './metadata.js';
+import { Query } from './query.js';
+import { type ScriptOptions, type ScriptResult } from './scripts.js';
+import type { FMSODataOptions, RequestOptions } from './types.js';
+import { type FMVersionMajor, type FMVersionInfo, type FMFeatureFlags, type FMServerVersion } from '@fms-odata/spec-ts';
+/**
+ * `FMSOData` is the entrypoint for all OData operations against a FileMaker
+ * Server database. Covers query/CRUD, script invocation, container I/O,
+ * `$metadata` introspection, and `$batch` operations.
+ */
+export declare class FMSOData {
+    readonly host: string;
+    readonly database: string;
+    readonly baseUrl: string;
+    readonly timeoutMs: number | undefined;
+    /** @internal */ readonly _ctx: HttpClientContext;
+    /** @internal */ private _metadataFetcher?;
+    constructor(options: FMSODataOptions);
+    /**
+     * Start a query against the given entity set (FileMaker layout name).
+     */
+    from<T = Record<string, unknown>>(entitySet: string): Query<T>;
+    /**
+     * Low-level escape hatch: execute a raw request against a path relative to
+     * the database base URL (or an absolute URL). Returns the parsed JSON body.
+     *
+     * @example
+     * ```ts
+     * const body = await db.request<{ value: unknown[] }>('/contact?$top=1')
+     * ```
+     */
+    request<T = unknown>(pathOrUrl: string, opts?: HttpRequestOptions): Promise<T>;
+    /**
+     * Low-level escape hatch: execute a raw request and return the `Response`
+     * object directly (useful for binary / streaming responses).
+     */
+    rawRequest(pathOrUrl: string, opts?: HttpRequestOptions): Promise<Response>;
+    /**
+     * Invoke a FileMaker script at database scope.
+     *
+     * ```ts
+     * const result = await db.script('Ping', { parameter: 'hello' })
+     * console.log(result.scriptResult) // => string value returned by the script
+     * ```
+     *
+     * A non-zero `scriptError` is thrown as `FMScriptError`.
+     */
+    script(name: string, opts?: ScriptOptions): Promise<ScriptResult>;
+    /**
+     * Invoke a FileMaker script by its immutable FMSID.
+     *
+     * Requires FileMaker Server 2026+ (v26). Use `hasFeature('scriptsByFMSID')`
+     * to check before calling. FMSID-based invocation is more stable than
+     * name-based: it survives script renames and works across database
+     * migrations.
+     *
+     * ```ts
+     * const result = await db.scriptById(42, { parameter: 'hello' })
+     * ```
+     */
+    scriptById(fmsid: number, opts?: ScriptOptions): Promise<ScriptResult>;
+    /**
+     * Fetch the OData CSDL `$metadata` XML and parse it into a typed structure.
+     * Results are cached; pass `refresh: true` to force a refetch.
+     *
+     * ```ts
+     * const meta = await db.metadata()
+     * console.log(meta.entitySets.map(es => es.name))
+     * ```
+     */
+    metadata(opts?: MetadataOptions): Promise<ODataMetadata>;
+    /**
+     * Fetch the raw `$metadata` XML (escape hatch for debugging or custom parsing).
+     */
+    metadataXml(opts?: RequestOptions): Promise<string>;
+    /** @internal */ private _detectedVersion;
+    /** @internal */ private _detectedServerVersion;
+    /**
+     * Detect the FileMaker Server major version by fetching `$metadata` and
+     * parsing the version annotation using a multi-strategy approach (see
+     * `@fms-odata/spec-ts` `parseServerVersion`). The result is cached for the
+     * lifetime of this `FMSOData` instance.
+     *
+     * Returns the major version string (`'19'`, `'21'`, `'22'`, `'26'`) or
+     * `'future'` if the version is newer than the spec knows about. Returns
+     * `null` if the version cannot be determined (e.g. the metadata lacks the
+     * annotation).
+     *
+     * ```ts
+     * const v = await db.version()
+     * if (v === '26') console.log('Server is FileMaker 2026')
+     * ```
+     */
+    version(): Promise<FMVersionMajor | null>;
+    /**
+     * Get the full parsed FileMaker Server version (major, minor, patch, raw)
+     * by fetching `$metadata` and parsing the version annotation. The result is
+     * cached for the lifetime of this `FMSOData` instance.
+     *
+     * Returns `null` if the version cannot be determined.
+     *
+     * ```ts
+     * const sv = await db.serverVersion()
+     * if (sv) console.log(`Server is ${sv.raw} (major ${sv.major})`)
+     * ```
+     */
+    serverVersion(): Promise<FMServerVersion | null>;
+    /**
+     * Get the full version info (feature flags + query option flags) for the
+     * detected server version. Fetches metadata if not already cached.
+     *
+     * Returns `null` if the version cannot be determined.
+     *
+     * ```ts
+     * const info = await db.versionInfo()
+     * if (info?.features.applyAggregation) {
+     *   // Server supports $apply
+     * }
+     * ```
+     */
+    versionInfo(): Promise<FMVersionInfo | null>;
+    /**
+     * Check if the server supports a specific feature. Fetches metadata (to
+     * detect the version) on first call; subsequent calls use the cached result.
+     *
+     * Returns `false` if the version cannot be determined.
+     *
+     * ```ts
+     * if (await db.hasFeature('applyAggregation')) {
+     *   const result = await db.from('orders').apply(...)
+     * }
+     * ```
+     */
+    hasFeature(feature: keyof FMFeatureFlags): Promise<boolean>;
+    /**
+     * Create a new `$batch` builder for composing multiple OData operations
+     * into a single HTTP round-trip.
+     *
+     * Read operations (`add`) are executed independently. Write operations
+     * (`changeset`) are grouped atomically — all succeed or all fail.
+     *
+     * ```ts
+     * const batch = db.batch()
+     * const contacts = batch.add({ op: 'list', entitySet: 'contact', query: { $top: 5 } })
+     * batch.changeset(cs => {
+     *   cs.create('contact', { firstName: 'A', lastName: 'B' })
+     *   cs.patch('contact', 123, { firstName: 'Updated' })
+     * })
+     * const result = await batch.send()
+     * console.log(await contacts._promise) // First op result
+     * ```
+     */
+    batch(): Batch;
+    /** @internal */
+    _resolveUrl(pathOrUrl: string): string;
+}
+export type { RequestOptions };
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAA+B,KAAK,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,WAAW,CAAA;AACxG,OAAO,EAAmB,KAAK,eAAe,EAAE,KAAK,aAAa,EAAE,MAAM,eAAe,CAAA;AACzF,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAgD,KAAK,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,cAAc,CAAA;AAClH,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AACjE,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,eAAe,EAGrB,MAAM,oBAAoB,CAAA;AAE3B;;;;GAIG;AACH,qBAAa,QAAQ;IACnB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;IAEtC,gBAAgB,CAAC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAA;IACjD,gBAAgB,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAAiB;gBAE/C,OAAO,EAAE,eAAe;IAoBpC;;OAEG;IACH,IAAI,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC;IAK9D;;;;;;;;OAQG;IACG,OAAO,CAAC,CAAC,GAAG,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,CAAC,CAAC;IAIxF;;;OAGG;IACG,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,GAAE,kBAAuB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAIrF;;;;;;;;;OASG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;IAI3E;;;;;;;;;;;OAWG;IACG,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,aAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;IAIhF;;;;;;;;OAQG;IACG,QAAQ,CAAC,IAAI,GAAE,eAAoB,GAAG,OAAO,CAAC,aAAa,CAAC;IAOlE;;OAEG;IACG,WAAW,CAAC,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,CAAC;IAW7D,gBAAgB,CAAC,OAAO,CAAC,gBAAgB,CAAmC;IAC5E,gBAAgB,CAAC,OAAO,CAAC,sBAAsB,CAAoC;IAEnF;;;;;;;;;;;;;;;OAeG;IACG,OAAO,IAAI,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAkB/C;;;;;;;;;;;OAWG;IACG,aAAa,IAAI,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAYtD;;;;;;;;;;;;OAYG;IACG,WAAW,IAAI,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;IAMlD;;;;;;;;;;;OAWG;IACG,UAAU,CAAC,OAAO,EAAE,MAAM,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAMjE;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,IAAI,KAAK;IAId,gBAAgB;IAChB,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM;CAKvC;AAGD,YAAY,EAAE,cAAc,EAAE,CAAA"}

package/dist/containers.d.ts

@@ -0,0 +1,190 @@
+/**
+ * FileMaker container field I/O.
+ *
+ * FMS exposes three container operations over OData v4 — see
+ * `docs/filemaker-odata-container-guide.md` for the full reference. The
+ * library maps to them as follows:
+ *
+ *   GET   /<EntitySet>(<key>)/<field>/$value   → ContainerRef#get / getStream
+ *   PATCH /<EntitySet>(<key>)/<field>          → ContainerRef#upload({ encoding: 'binary' }) — DEFAULT
+ *   PATCH /<EntitySet>(<key>) (JSON body)      → ContainerRef#upload({ encoding: 'base64' })
+ *   POST  /<EntitySet>           (JSON body)   → Query#create({ … }) with container annotation keys
+ *
+ * Supported MIME types per the Claris guide:
+ *   image/png, image/jpeg, image/gif, image/tiff, application/pdf
+ *
+ * Clearing a container is not in the Claris guide. The library PATCHes the
+ * record with `{ <field>: null }`.
+ */
+import type { EntityRef } from './entity.js';
+import type { RequestOptions } from './types.js';
+/** Result of a successful container download. */
+export interface ContainerDownload {
+    /** Binary contents as a `Blob` (works in browsers, Web Viewer, and Node 18+). */
+    blob: Blob;
+    /** MIME type reported by FMS (e.g. `image/png`); empty string if absent. */
+    contentType: string;
+    /** Filename parsed from `Content-Disposition`, when present. */
+    filename?: string;
+    /** Byte length. `0` indicates an empty container. */
+    size: number;
+}
+/** Input accepted by `ContainerRef#upload`. */
+export interface ContainerUploadInput {
+    /** Binary payload. `fetch` accepts all three forms natively. */
+    data: Blob | ArrayBuffer | Uint8Array;
+    /**
+     * Content-Type to send with the upload. Optional: when omitted, the library
+     * sniffs the MIME from the payload's magic bytes (PNG, JPEG, GIF, TIFF, PDF).
+     * Throws if it cannot detect a supported type.
+     */
+    contentType?: string;
+    /**
+     * Optional filename to store in the container. Surfaced on download via
+     * `Content-Disposition: attachment; filename="…"`. When omitted, FMS stores
+     * (and surfaces back) the auto-generated name `Untitled.png`.
+     */
+    filename?: string;
+    /**
+     * Wire format:
+     *
+     * - `'binary'` (default): PATCH `…/<field>` with raw bytes. Restricted to
+     *   PNG, JPEG, GIF, TIFF, and PDF.
+     * - `'base64'`: PATCH `…/<EntitySet>(<key>)` with a JSON body containing
+     *   the file as a base64 string plus `@com.filemaker.odata.…` annotations.
+     *   Use this when you need to update multiple container fields (or mix
+     *   container and regular field updates) in a single request.
+     */
+    encoding?: 'binary' | 'base64';
+}
+/**
+ * MIME types FMS accepts for container fields. Other types (audio, video,
+ * zip, docx, …) may upload but won't be classified as a media type and won't
+ * preview correctly in FileMaker.
+ */
+export declare const FM_CONTAINER_SUPPORTED_MIME_TYPES: readonly ["image/png", "image/jpeg", "image/gif", "image/tiff", "application/pdf"];
+export type FMContainerMimeType = (typeof FM_CONTAINER_SUPPORTED_MIME_TYPES)[number];
+/**
+ * Sniff the MIME type from the magic bytes of an uploaded payload. Returns
+ * `undefined` when none of the supported signatures match.
+ *
+ * Signatures:
+ *   PNG  — 89 50 4E 47 0D 0A 1A 0A
+ *   JPEG — FF D8 FF
+ *   GIF  — 47 49 46 38 (`GIF8`)
+ *   TIFF — 49 49 2A 00 (little-endian) | 4D 4D 00 2A (big-endian)
+ *   PDF  — 25 50 44 46 (`%PDF`)
+ *
+ * @internal
+ */
+export declare function sniffContainerMime(bytes: Uint8Array): FMContainerMimeType | undefined;
+/**
+ * Handle to a single FileMaker container field on a specific record. Created
+ * via `EntityRef#container(fieldName)`.
+ */
+export declare class ContainerRef {
+    /** @internal */ readonly _entity: EntityRef<unknown>;
+    readonly fieldName: string;
+    constructor(entity: EntityRef<unknown>, fieldName: string);
+    /**
+     * Absolute URL of the container field itself
+     * (`…/<EntitySet>(<key>)/<fieldName>`). This is the URL used by binary
+     * `upload()`. Append `/$value` to download.
+     */
+    url(): string;
+    /** @internal — `…/<field>/$value` for downloads. */
+    private _valueUrl;
+    /**
+     * Download the container's contents and buffer them into a `Blob`. For
+     * very large payloads prefer `getStream()` to avoid buffering in memory.
+     */
+    get(opts?: RequestOptions): Promise<ContainerDownload>;
+    /**
+     * Stream the container's contents without buffering. Useful for large files
+     * (`pipeTo()` into a writable, forward to another `Response`, etc.).
+     *
+     * Throws if the underlying `Response` has no body.
+     */
+    getStream(opts?: RequestOptions): Promise<ReadableStream<Uint8Array>>;
+    /**
+     * Upload binary contents to the container. Replaces any existing value.
+     *
+     * Default `encoding: 'binary'` PATCHes `…/<field>` with raw bytes and a
+     * `Content-Type` header. Restricted to PNG / JPEG / GIF / TIFF / PDF.
+     *
+     * `encoding: 'base64'` PATCHes `…/<EntitySet>(<key>)` with a JSON body
+     * containing base64 data plus `@com.filemaker.odata.…` annotations. Use
+     * this when updating multiple container fields (or mixing container and
+     * regular fields) in a single round-trip.
+     *
+     * `contentType` is optional — when omitted, the library sniffs the MIME
+     * from the payload's magic bytes. Throws if no supported signature matches.
+     */
+    upload(input: ContainerUploadInput, opts?: RequestOptions): Promise<void>;
+    /**
+     * Clear the container value. FMS has no documented per-field DELETE for
+     * record-level data, so the supported path is to PATCH the record with
+     * `{ <fieldName>: null }`.
+     */
+    delete(opts?: RequestOptions): Promise<void>;
+}
+/**
+ * One container value to embed in a JSON body, in raw byte form. Used by
+ * `buildContainerJsonBody` and `EntityRef#patchContainers`.
+ */
+export interface ContainerJsonValue {
+    /** Base64-encoded bytes (without `data:` prefix or whitespace). */
+    data: string;
+    /** REQUIRED MIME type. Stored as `@com.filemaker.odata.ContentType`. */
+    contentType: string;
+    /** Optional filename. Stored as `@com.filemaker.odata.Filename`. */
+    filename?: string;
+}
+/**
+ * Build a JSON body for a POST/PATCH that updates one or more container
+ * fields (and optionally regular fields). Inserts the FileMaker annotation
+ * keys for every container value.
+ *
+ * @example
+ * buildContainerJsonBody(
+ *   {
+ *     photo: { data: '<base64>', contentType: 'image/png', filename: 'p.png' },
+ *     contract: { data: '<base64>', contentType: 'application/pdf' },
+ *   },
+ *   { website: 'https://example.com' },
+ * )
+ */
+export declare function buildContainerJsonBody(containers: Record<string, ContainerJsonValue>, regularFields?: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Parse the `filename` (or RFC 5987 `filename*`) from a `Content-Disposition`
+ * header. Returns `undefined` when no filename parameter is present.
+ *
+ * Per RFC 6266 §4.3, `filename*` (with explicit charset) takes precedence
+ * over `filename` when both are supplied.
+ *
+ * @internal
+ */
+export declare function parseContentDispositionFilename(value: string): string | undefined;
+/**
+ * Build a `Content-Disposition` value for an upload. The disposition-type is
+ * `inline` to match the example in the Claris OData docs.
+ *
+ * The Claris doc example uses the **unquoted** form
+ * (`filename=ALFKI.png`); FMS has been observed to mis-parse the RFC 6266
+ * quoted form on some deployments. So when the filename is composed of
+ * RFC 7230 token characters this function emits the unquoted form, falls
+ * back to a quoted form when the name contains spaces or other separator
+ * characters, and additionally emits an RFC 5987 `filename*=UTF-8''…`
+ * parameter for non-ASCII names.
+ *
+ * @internal
+ */
+export declare function formatContentDisposition(filename: string): string;
+/**
+ * Encode bytes to a base64 string. Uses Node's `Buffer` when available, else
+ * a chunked `btoa` fallback (avoids stack overflow on large arrays).
+ *
+ * @internal
+ */
+export declare function toBase64(bytes: Uint8Array): string;
+//# sourceMappingURL=containers.d.ts.map

package/dist/containers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"containers.d.ts","sourceRoot":"","sources":["../src/containers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AAE5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAGhD,iDAAiD;AACjD,MAAM,WAAW,iBAAiB;IAChC,iFAAiF;IACjF,IAAI,EAAE,IAAI,CAAA;IACV,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAA;IACnB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAA;CACb;AAED,+CAA+C;AAC/C,MAAM,WAAW,oBAAoB;IACnC,gEAAgE;IAChE,IAAI,EAAE,IAAI,GAAG,WAAW,GAAG,UAAU,CAAA;IACrC;;;;OAIG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;CAC/B;AAED;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,oFAMpC,CAAA;AAEV,MAAM,MAAM,mBAAmB,GAAG,CAAC,OAAO,iCAAiC,CAAC,CAAC,MAAM,CAAC,CAAA;AAYpF;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,UAAU,GAAG,mBAAmB,GAAG,SAAS,CAuBrF;AAED;;;GAGG;AACH,qBAAa,YAAY;IACvB,gBAAgB,CAAC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;gBAEd,MAAM,EAAE,SAAS,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,MAAM;IAQzD;;;;OAIG;IACH,GAAG,IAAI,MAAM;IAIb,oDAAoD;IACpD,OAAO,CAAC,SAAS;IAIjB;;;OAGG;IACG,GAAG,CAAC,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAyBhE;;;;;OAKG;IACG,SAAS,CAAC,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;IAa/E;;;;;;;;;;;;;OAaG;IACG,MAAM,CAAC,KAAK,EAAE,oBAAoB,EAAE,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAiEnF;;;;OAIG;IACG,MAAM,CAAC,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;CAavD;AAMD;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,WAAW,EAAE,MAAM,CAAA;IACnB,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,EAC9C,aAAa,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAC1C,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazB;AAMD;;;;;;;;GAQG;AACH,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAyBjF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAejE;AAaD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAclD"}

package/dist/entity.d.ts

@@ -0,0 +1,149 @@
+/**
+ * Single-entity handle returned by `Query#byKey(key)`. Supports `.get()`,
+ * `.patch()`, `.delete()`, `.script()` (record-scope FileMaker script
+ * invocation, v0.1.4+), and `.container(field)` (container-field binary
+ * I/O, v0.1.5+).
+ */
+import type { FMSOData } from './client.js';
+import { ContainerRef, type ContainerJsonValue } from './containers.js';
+import { type ScriptOptions, type ScriptResult } from './scripts.js';
+import type { RequestOptions } from './types.js';
+import { type ODataLiteral } from './url.js';
+/** Options accepted by mutating entity operations. */
+export interface EntityWriteOptions extends RequestOptions {
+    /**
+     * Optional `If-Match` precondition. Pass an ETag returned from a prior read
+     * to enable optimistic concurrency.
+     */
+    ifMatch?: string;
+    /**
+     * Whether the server should return the updated representation. Defaults to
+     * `false` (`Prefer: return=minimal`) to match FMS behaviour; set to `true`
+     * to request `Prefer: return=representation`.
+     */
+    returnRepresentation?: boolean;
+}
+/**
+ * Handle to a single OData entity. Holds the client, entity-set name, and the
+ * primary key; every method builds a URL of the form
+ * `<baseUrl>/<EntitySet>(<key>)` and delegates to the shared HTTP executor.
+ */
+export declare class EntityRef<T = Record<string, unknown>> {
+    readonly entitySet: string;
+    readonly key: ODataLiteral;
+    /** @internal */ readonly _client: FMSOData;
+    constructor(client: FMSOData, entitySet: string, key: ODataLiteral);
+    /** Absolute URL for this entity. */
+    toURL(): string;
+    /** `GET` the entity. Returns the parsed JSON row. */
+    get(opts?: RequestOptions): Promise<T>;
+    /**
+     * `GET` a single field's scalar value via the OData property URL
+     * (`…/<EntitySet>(<key>)/<fieldName>`). FMS responds with the JSON envelope
+     * `{ value: … }`; this method unwraps it and returns just the value.
+     *
+     * Useful when you only need one column without composing a `$select` query.
+     * For container fields use `container(name).get()` instead.
+     */
+    fieldValue<V = unknown>(fieldName: string, opts?: RequestOptions): Promise<V>;
+    /**
+     * `PATCH` the entity with partial values. Returns the updated row when the
+     * server echoes one (OData `Prefer: return=representation`), otherwise
+     * `undefined` on `204 No Content`.
+     */
+    patch(body: Partial<T> | Record<string, unknown>, opts?: EntityWriteOptions): Promise<T | undefined>;
+    /** `DELETE` the entity. Resolves on success; throws `FMSODataError` otherwise. */
+    delete(opts?: EntityWriteOptions): Promise<void>;
+    /**
+     * Invoke a FileMaker script in the context of this single record. FMS sets
+     * the script's current record to this entity before running it.
+     */
+    script(name: string, opts?: ScriptOptions): Promise<ScriptResult>;
+    /**
+     * Get a typed handle to one of this record's container fields, exposing
+     * `.get()`, `.getStream()`, `.upload(...)`, and `.delete()`.
+     */
+    container(fieldName: string): ContainerRef;
+    /**
+     * Update one or more container fields (and optionally regular fields) on
+     * this record in a single base64 PATCH request. This maps to the Claris
+     * "Operation 3" (`PATCH /<EntitySet>(<key>)` with JSON body containing
+     * `<field>`, `<field>@com.filemaker.odata.ContentType`, and
+     * `<field>@com.filemaker.odata.Filename`).
+     *
+     * Each container value's `data` must already be base64-encoded (use the
+     * library's exported `toBase64()` helper or `Buffer.from(bytes).toString('base64')`).
+     *
+     * @example
+     * await db.from('contact').byKey(7).patchContainers(
+     *   {
+     *     photo:    { data: photoB64,    contentType: 'image/png',       filename: 'p.png' },
+     *     contract: { data: contractB64, contentType: 'application/pdf', filename: 'c.pdf' },
+     *   },
+     *   { website: 'https://example.com' },
+     * )
+     */
+    patchContainers(containers: Record<string, ContainerJsonValue>, regularFields?: Record<string, unknown>, opts?: EntityWriteOptions): Promise<void>;
+    /**
+     * Get the references for a navigation property on this record.
+     *
+     * `GET /<EntitySet>(<key>)/<navProperty>/$ref`
+     *
+     * Returns an array of entity references. For a single-valued navigation
+     * property, the array has at most one element.
+     *
+     * @example
+     * ```ts
+     * const refs = await db.from('contact').byKey(7).getRefs('addresses')
+     * // [{ '@odata.id': 'https://fms.example.com/fmi/odata/v4/DB/address(1)' }, ...]
+     * ```
+     */
+    getRefs(navProperty: string, opts?: RequestOptions): Promise<EntityRefInfo[]>;
+    /**
+     * Add a reference to a related record via a navigation property.
+     *
+     * `POST /<EntitySet>(<key>)/<navProperty>/$ref`
+     *
+     * For single-valued navigation properties, use `setRef()` instead (PATCH).
+     *
+     * @example
+     * ```ts
+     * await db.from('contact').byKey(7).addRef('addresses', 42)
+     * ```
+     */
+    addRef(navProperty: string, relatedKey: string | number, opts?: EntityWriteOptions): Promise<void>;
+    /**
+     * Set (replace) the reference for a single-valued navigation property.
+     *
+     * `PATCH /<EntitySet>(<key>)/<navProperty>/$ref`
+     *
+     * @example
+     * ```ts
+     * await db.from('order').byKey(100).setRef('customer', 7)
+     * ```
+     */
+    setRef(navProperty: string, relatedKey: string | number, opts?: EntityWriteOptions): Promise<void>;
+    /**
+     * Remove a reference from a navigation property.
+     *
+     * `DELETE /<EntitySet>(<key>)/<navProperty>/$ref`
+     *
+     * For collection-valued navigation properties, pass the `relatedKey` to
+     * remove a specific reference. For single-valued, omit `relatedKey` to
+     * clear the reference.
+     *
+     * @example
+     * ```ts
+     * await db.from('contact').byKey(7).removeRef('addresses', 42)
+     * await db.from('order').byKey(100).removeRef('customer')
+     * ```
+     */
+    removeRef(navProperty: string, relatedKey?: string | number, opts?: EntityWriteOptions): Promise<void>;
+    /** @internal — build a relative @odata.id for a related entity. */
+    private _refId;
+}
+/** Entity reference info returned by `getRefs()`. */
+export interface EntityRefInfo {
+    '@odata.id': string;
+}
+//# sourceMappingURL=entity.d.ts.map