fms-odata-js 0.3.0

package/dist/scripts.d.ts

@@ -0,0 +1,114 @@
+/**
+ * FileMaker script invocation.
+ *
+ * FMS exposes FileMaker scripts through the OData v4 Action mechanism at a
+ * `Script.<ScriptName>` path suffix. Scripts can be invoked at three scopes:
+ *
+ *   POST /<db>/Script.<name>                       // database-level
+ *   POST /<db>/<EntitySet>/Script.<name>           // entity-set context
+ *   POST /<db>/<EntitySet>(<key>)/Script.<name>    // single-record context
+ *
+ * Starting with FileMaker Server 2026 (v26), scripts can also be invoked by
+ * their immutable FMSID instead of the name:
+ *
+ *   POST /<db>/Script.FMSID:<id>                   // database-level
+ *   POST /<db>/<EntitySet>/Script.FMSID:<id>       // entity-set context
+ *   POST /<db>/<EntitySet>(<key>)/Script.FMSID:<id> // single-record context
+ *
+ * The optional parameter is sent as `{ "scriptParameterValue": "<string>" }`. The
+ * response envelope is `{ "scriptResult": "...", "scriptError": "0" }`; a
+ * non-zero `scriptError` becomes an `FMScriptError`.
+ *
+ * @see https://github.com/fsans/fms-odata-spec/blob/main/docs/06-scripts.md
+ */
+import type { FMSOData } from './client.js';
+import type { RequestOptions } from './types.js';
+import { type ODataLiteral } from './url.js';
+/** Script identifier: either by name or by FMSID (v26+). */
+export type ScriptIdentifier = {
+    type: 'name';
+    name: string;
+} | {
+    type: 'fmsid';
+    id: number;
+};
+/** Options accepted by a script invocation. */
+export interface ScriptOptions extends RequestOptions {
+    /**
+     * Optional script parameter. Serialized to the FMS `scriptParameterValue`
+     * field in the request body. If omitted, the body is empty and the script
+     * runs with no parameter (FileMaker's `Get(ScriptParameter)` returns empty).
+     */
+    parameter?: string;
+}
+/**
+ * Result envelope returned by a successful script invocation. A non-zero
+ * `scriptError` is promoted to an `FMScriptError` before reaching the caller,
+ * so values you receive here always represent success (`scriptError === "0"`).
+ */
+export interface ScriptResult {
+    /** Raw value returned by `Exit Script [Text Result: ...]`. */
+    scriptResult?: string;
+    /** Always `"0"` in a resolved result; non-zero raises `FMScriptError`. */
+    scriptError: string;
+    /** Full parsed response body, for forward-compatible field access. */
+    raw: unknown;
+}
+/** Scope describing where a `ScriptInvoker` is rooted. */
+export interface ScriptScope {
+    /** When omitted the script runs at database scope. */
+    entitySet?: string;
+    /** When present alongside `entitySet`, the script runs at record scope. */
+    key?: ODataLiteral;
+}
+/**
+ * Low-level handle used internally by `FMSOData#script`, `Query#script`, and
+ * `EntityRef#script`. Exposed so advanced callers can build their own
+ * invocation paths if needed.
+ */
+export declare class ScriptInvoker {
+    /** @internal */ readonly _client: FMSOData;
+    readonly entitySet: string | undefined;
+    readonly key: ODataLiteral | undefined;
+    constructor(client: FMSOData, scope?: ScriptScope);
+    /** Build the absolute URL for invoking `name` at this scope. */
+    url(name: string): string;
+    /** Build the absolute URL for invoking by FMSID at this scope. */
+    urlById(fmsid: number): string;
+    /** @internal — build URL from a script path segment. */
+    private _urlForSegment;
+    /** Invoke the script by name. Resolves to a `ScriptResult` on success. */
+    run(name: string, opts?: ScriptOptions): Promise<ScriptResult>;
+    /**
+     * Invoke the script by its immutable FMSID.
+     *
+     * Requires FileMaker Server 2026+ (v26). Use `db.hasFeature('scriptsByFMSID')`
+     * to check before calling.
+     *
+     * ```ts
+     * const result = await db.scriptById(42, { parameter: 'hello' })
+     * ```
+     */
+    runById(fmsid: number, opts?: ScriptOptions): Promise<ScriptResult>;
+    /** @internal — execute a script POST at the given URL. */
+    private _runAtUrl;
+}
+/**
+ * Parse the `{ scriptResult, scriptError }` envelope FMS returns from a
+ * script action, promoting a non-zero `scriptError` to `FMScriptError`.
+ *
+ * @internal
+ */
+export declare function parseScriptEnvelope(raw: unknown, request: {
+    url: string;
+    method: string;
+}): ScriptResult;
+/** @internal — convenience factory used by client/query/entity helpers. */
+export declare function runScriptAtDatabase(client: FMSOData, name: string, opts?: ScriptOptions): Promise<ScriptResult>;
+/** @internal — convenience factory for FMSID-based invocation. */
+export declare function runScriptByIdAtDatabase(client: FMSOData, fmsid: number, opts?: ScriptOptions): Promise<ScriptResult>;
+/** @internal */
+export declare function runScriptAtEntitySet(client: FMSOData, entitySet: string, name: string, opts?: ScriptOptions): Promise<ScriptResult>;
+/** @internal */
+export declare function runScriptAtEntity(client: FMSOData, entitySet: string, key: ODataLiteral, name: string, opts?: ScriptOptions): Promise<ScriptResult>;
+//# sourceMappingURL=scripts.d.ts.map

package/dist/scripts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scripts.d.ts","sourceRoot":"","sources":["../src/scripts.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Public TypeScript types for fms-odata-js.
+ *
+ * These are intentionally minimal during M1 and will be expanded in later
+ * milestones (query, CRUD, containers, scripts, metadata, batch).
+ */
+export type TokenProvider = string | (() => string | Promise<string>);
+export interface FMSODataOptions {
+    /** Base FMS host, e.g. `https://fms.example.com` (no trailing slash). */
+    host: string;
+    /** FileMaker database (solution) name. */
+    database: string;
+    /** Bearer token or resolver. */
+    token: TokenProvider;
+    /** Invoked once on 401 to refresh credentials before a single retry. */
+    onUnauthorized?: () => void | Promise<void>;
+    /** Injectable fetch implementation (defaults to `globalThis.fetch`). */
+    fetch?: typeof globalThis.fetch;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs?: number;
+}
+/** Common request-level options accepted by every method. */
+export interface RequestOptions {
+    signal?: AbortSignal;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,MAAM,aAAa,GACrB,MAAM,GACN,CAAC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAA;AAEpC,MAAM,WAAW,eAAe;IAC9B,yEAAyE;IACzE,IAAI,EAAE,MAAM,CAAA;IACZ,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAA;IAChB,gCAAgC;IAChC,KAAK,EAAE,aAAa,CAAA;IACpB,wEAAwE;IACxE,cAAc,CAAC,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC3C,wEAAwE;IACxE,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;IAC/B,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,6DAA6D;AAC7D,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAA;CACrB"}

package/dist/url.d.ts

@@ -0,0 +1,49 @@
+/**
+ * OData URL encoding helpers.
+ *
+ * Aligned with `@fms-odata/spec-ts` for the shared helpers (`escapeStringLiteral`,
+ * `formatLiteral`). fms-odata-js keeps its richer implementations for
+ * `formatDateTime`, `parseDateTime`, `odataEncode`, `buildQueryString`, and
+ * `encodePathSegment` which go beyond the spec's minimal versions.
+ *
+ * - String literals are single-quoted with inner single-quotes doubled.
+ * - Dates serialize as UTC ISO-8601 without milliseconds (FileMaker quirk).
+ * - Query-string keys are emitted verbatim (always safe ASCII such as `$filter`)
+ *   while values are percent-encoded via `odataEncode`, which uses `%20`
+ *   for spaces rather than `+` (required by OData `$filter`) and preserves
+ *   commas (required by `$select`, `$orderby`, `$expand`).
+ *
+ * @see https://github.com/fsans/fms-odata-spec/blob/main/docs/13-quirks.md
+ */
+/** Any value that can appear on the right-hand side of an OData `$filter` comparison. */
+export type ODataLiteral = string | number | boolean | Date | null | undefined;
+/** Escape a string for inclusion inside a single-quoted OData literal. */
+export declare function escapeStringLiteral(s: string): string;
+/** Format a `Date` as UTC ISO-8601 without milliseconds (e.g. `2026-04-17T14:45:00Z`). */
+export declare function formatDateTime(d: Date): string;
+/** Parse an OData DateTimeOffset string (with or without milliseconds). */
+export declare function parseDateTime(s: string): Date;
+/** Format a primitive as an OData literal suitable for `$filter`, `$search`, etc. */
+export declare function formatLiteral(v: ODataLiteral): string;
+/** Encode a single URL path segment (spaces become `%20`). */
+export declare function encodePathSegment(s: string): string;
+/**
+ * Encode an OData query-string value.
+ *
+ * - Spaces become `%20` (not `+`) — required by OData `$filter`.
+ * - Commas stay literal (not `%2C`) — required by `$select`, `$orderby`, `$expand`.
+ * - Parentheses stay literal (not `%28`/`%29`) — required by `$apply` expressions
+ *   such as `aggregate(...)` and `groupby((...))`.
+ * - `$`, `=`, and `;` stay literal — required for nested `$expand` options.
+ *   FileMaker Server rejects percent-encoded forms of these characters.
+ */
+export declare function odataEncode(v: string): string;
+/**
+ * Build a querystring from ordered `[key, value]` pairs.
+ *
+ * Keys are emitted verbatim (the caller controls them and they are always safe
+ * ASCII such as `$filter`). Values are percent-encoded via `odataEncode`.
+ * Empty / nullish values are skipped.
+ */
+export declare function buildQueryString(params: ReadonlyArray<readonly [string, string]>): string;
+//# sourceMappingURL=url.d.ts.map

package/dist/url.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../src/url.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,yFAAyF;AACzF,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,IAAI,GAAG,SAAS,CAAA;AAE9E,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAErD;AAED,0FAA0F;AAC1F,wBAAgB,cAAc,CAAC,CAAC,EAAE,IAAI,GAAG,MAAM,CAK9C;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,IAAI,CAM7C;AAED,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,CAAC,EAAE,YAAY,GAAG,MAAM,CAYrD;AAED,8DAA8D;AAC9D,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ7C;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,aAAa,CAAC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,MAAM,CAOzF"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "fms-odata-js",
+  "version": "0.3.0",
+  "description": "Zero-runtime-dependency TypeScript client for FileMaker Server OData v4 (Web Viewer, browser, Node).",
+  "type": "module",
+  "main": "./dist/fms-odata.esm.js",
+  "module": "./dist/fms-odata.esm.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/fms-odata.esm.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "npm run build:types && npm run build:esm && npm run build:min && npm run build:iife",
+    "build:types": "tsc -p tsconfig.build.json",
+    "build:esm": "esbuild src/index.ts --bundle --format=esm --target=es2020 --outfile=dist/fms-odata.esm.js",
+    "build:min": "esbuild src/index.ts --bundle --format=esm --target=es2020 --minify --outfile=dist/fms-odata.esm.min.js",
+    "build:iife": "esbuild src/index.ts --bundle --format=iife --global-name=FMSODataLib --target=es2017 --minify --outfile=dist/fms-odata.iife.min.js",
+    "test": "vitest run",
+    "test:unit": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "playwright test",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint \"src/**/*.ts\" \"tests/**/*.ts\"",
+    "format": "prettier --write .",
+    "size": "gzip -c dist/fms-odata.esm.min.js | wc -c",
+    "probe": "node scripts/probe.mjs"
+  },
+  "keywords": [
+    "filemaker",
+    "fms",
+    "odata",
+    "rest",
+    "web-viewer",
+    "typescript"
+  ],
+  "license": "MIT",
+  "author": "Francesc Sans <tecnic.at.ntwk.es> (nBCN Software, Barcelona — http://www.ntwk.es)",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@fms-odata/spec-ts": "^1.1.0",
+    "@playwright/test": "^1.47.0",
+    "@types/node": "^20.14.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "esbuild": "^0.23.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  }
+}