fms-odata-js 0.3.0 → 0.4.1

package/src/schema.ts

@@ -0,0 +1,236 @@
+/**
+ * Schema modification (DDL) for FileMaker Server via the OData system tables.
+ *
+ * FMS exposes DDL through two system tables:
+ *
+ *   FileMaker_Tables   — create tables, add fields, delete tables/fields
+ *   FileMaker_Indexes  — create and delete field indexes
+ *
+ * All operations require a FileMaker account with full access (schema
+ * modification) privileges in the target file.
+ *
+ * Destructive operations (`deleteTable`, `deleteField`) require an explicit
+ * `confirm: true` option to prevent accidental data loss, per the spec's
+ * security guidance (docs/10-schema-modification.md).
+ *
+ * @see https://github.com/fsans/fms-odata-spec/blob/main/docs/10-schema-modification.md
+ */
+
+import {
+  FIELD_TYPES,
+  parseFieldType,
+  type CreateTableParams,
+  type AddFieldsParams,
+  type FMFieldDefinition,
+} from '@fms-odata/spec-ts'
+import type { FMSOData } from './client.js'
+import { executeJson } from './http.js'
+import type { RequestOptions } from './types.js'
+import { encodePathSegment } from './url.js'
+
+/** Options accepted by schema operations. */
+export interface SchemaOptions extends RequestOptions {}
+
+/** Options for destructive schema operations (deleteTable, deleteField). */
+export interface DeleteSchemaOptions extends SchemaOptions {
+  /**
+   * Must be `true` to proceed. Destructive DDL operations permanently destroy
+   * data with no undo. This guard prevents accidental invocation.
+   */
+  confirm: true
+}
+
+/** Validate that every field definition uses a supported base type. */
+function validateFieldDefinitions(fields: FMFieldDefinition[]): void {
+  for (const f of fields) {
+    if (!f.name) throw new TypeError('SchemaEditor: field `name` is required')
+    if (!f.type) throw new TypeError('SchemaEditor: field `type` is required')
+    const { baseType } = parseFieldType(f.type)
+    const upper = baseType.toUpperCase()
+    if (!FIELD_TYPES.includes(upper as (typeof FIELD_TYPES)[number])) {
+      throw new TypeError(
+        `SchemaEditor: unsupported field type "${f.type}" (base: "${baseType}"). ` +
+          `Supported: ${FIELD_TYPES.join(', ')}`,
+      )
+    }
+  }
+}
+
+/**
+ * Schema editor for FileMaker DDL operations.
+ *
+ * Obtain an instance via `db.schema()` or use the convenience methods on
+ * `FMSOData` (`db.createTable`, `db.addFields`, etc.).
+ */
+export class SchemaEditor {
+  /** @internal */ readonly _client: FMSOData
+
+  constructor(client: FMSOData) {
+    this._client = client
+  }
+
+  /**
+   * Create a new table with the given field definitions.
+   *
+   * ```ts
+   * await db.schema().createTable({
+   *   tableName: 'Company',
+   *   fields: [
+   *     { name: 'Company ID', type: 'int', primary: true },
+   *     { name: 'Company Name', type: 'varchar(100)', nullable: false },
+   *   ],
+   * })
+   * ```
+   */
+  async createTable(
+    params: CreateTableParams,
+    opts: SchemaOptions = {},
+  ): Promise<unknown> {
+    if (!params.tableName) throw new TypeError('SchemaEditor: `tableName` is required')
+    if (!params.fields?.length) throw new TypeError('SchemaEditor: `fields` must be a non-empty array')
+    validateFieldDefinitions(params.fields)
+
+    const url = `${this._client.baseUrl}/FileMaker_Tables`
+    return executeJson<unknown>(this._client._ctx, url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(params),
+      accept: 'json',
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    })
+  }
+
+  /**
+   * Add fields to an existing table.
+   *
+   * ```ts
+   * await db.schema().addFields({
+   *   tableName: 'Company',
+   *   fields: [{ name: 'Phone', type: 'varchar(30)' }],
+   * })
+   * ```
+   */
+  async addFields(
+    params: AddFieldsParams,
+    opts: SchemaOptions = {},
+  ): Promise<unknown> {
+    if (!params.tableName) throw new TypeError('SchemaEditor: `tableName` is required')
+    if (!params.fields?.length) throw new TypeError('SchemaEditor: `fields` must be a non-empty array')
+    validateFieldDefinitions(params.fields)
+
+    const url = `${this._client.baseUrl}/FileMaker_Tables/${encodePathSegment(params.tableName)}`
+    return executeJson<unknown>(this._client._ctx, url, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ fields: params.fields }),
+      accept: 'json',
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    })
+  }
+
+  /**
+   * Delete a table and ALL its records. Irreversible.
+   *
+   * Requires `opts.confirm === true` as a safety guard.
+   *
+   * ```ts
+   * await db.schema().deleteTable('OldTable', { confirm: true })
+   * ```
+   */
+  async deleteTable(
+    tableName: string,
+    opts: DeleteSchemaOptions,
+  ): Promise<void> {
+    if (!tableName) throw new TypeError('SchemaEditor: `tableName` is required')
+    if (opts.confirm !== true) {
+      throw new TypeError(
+        `SchemaEditor: deleteTable("${tableName}") requires { confirm: true } — ` +
+          'this operation permanently destroys the table and all its records.',
+      )
+    }
+    const url = `${this._client.baseUrl}/FileMaker_Tables/${encodePathSegment(tableName)}`
+    await executeJson<void>(this._client._ctx, url, {
+      method: 'DELETE',
+      accept: 'json',
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    })
+  }
+
+  /**
+   * Delete a field from a table. Irreversible.
+   *
+   * Requires `opts.confirm === true` as a safety guard.
+   *
+   * ```ts
+   * await db.schema().deleteField('Company', 'OldField', { confirm: true })
+   * ```
+   */
+  async deleteField(
+    tableName: string,
+    fieldName: string,
+    opts: DeleteSchemaOptions,
+  ): Promise<void> {
+    if (!tableName) throw new TypeError('SchemaEditor: `tableName` is required')
+    if (!fieldName) throw new TypeError('SchemaEditor: `fieldName` is required')
+    if (opts.confirm !== true) {
+      throw new TypeError(
+        `SchemaEditor: deleteField("${tableName}", "${fieldName}") requires { confirm: true } — ` +
+          'this operation permanently destroys the field and all its data.',
+      )
+    }
+    const url = `${this._client.baseUrl}/FileMaker_Tables/${encodePathSegment(tableName)}/${encodePathSegment(fieldName)}`
+    await executeJson<void>(this._client._ctx, url, {
+      method: 'DELETE',
+      accept: 'json',
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    })
+  }
+
+  /**
+   * Create an index on a field.
+   *
+   * ```ts
+   * await db.schema().createIndex('Company', 'Company Name')
+   * ```
+   */
+  async createIndex(
+    tableName: string,
+    fieldName: string,
+    opts: SchemaOptions = {},
+  ): Promise<unknown> {
+    if (!tableName) throw new TypeError('SchemaEditor: `tableName` is required')
+    if (!fieldName) throw new TypeError('SchemaEditor: `fieldName` is required')
+
+    const url = `${this._client.baseUrl}/FileMaker_Indexes/${encodePathSegment(tableName)}`
+    return executeJson<unknown>(this._client._ctx, url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ indexName: fieldName }),
+      accept: 'json',
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    })
+  }
+
+  /**
+   * Delete an index from a field.
+   *
+   * ```ts
+   * await db.schema().deleteIndex('Company', 'Company Name')
+   * ```
+   */
+  async deleteIndex(
+    tableName: string,
+    fieldName: string,
+    opts: SchemaOptions = {},
+  ): Promise<void> {
+    if (!tableName) throw new TypeError('SchemaEditor: `tableName` is required')
+    if (!fieldName) throw new TypeError('SchemaEditor: `fieldName` is required')
+
+    const url = `${this._client.baseUrl}/FileMaker_Indexes/${encodePathSegment(tableName)}/${encodePathSegment(fieldName)}`
+    await executeJson<void>(this._client._ctx, url, {
+      method: 'DELETE',
+      accept: 'json',
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    })
+  }
+}

package/src/scripts.ts

@@ -15,9 +15,12 @@
  *   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`.
+ * The optional parameter is sent as `{ "scriptParameterValue": ... }` (string,
+ * number or JSON object). The response envelope depends on the FMS version:
+ * older servers reply `{ "scriptResult": "...", "scriptError": "0" }`, while
+ * FMS v26+ nests the result as
+ * `{ "scriptResult": { "code": 0, "resultParameter": "...", "message": "..." } }`.
+ * A non-zero error code becomes an `FMScriptError`.
  *
  * @see https://github.com/fsans/fms-odata-spec/blob/main/docs/06-scripts.md
  */
@@ -41,10 +44,11 @@ export type ScriptIdentifier =
 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).
+   * field in the request body. FMS accepts a string, a number or a JSON
+   * object. If omitted, the body is empty and the script runs with no
+   * parameter (FileMaker's `Get(ScriptParameter)` returns empty).
    */
-  parameter?: string
+  parameter?: string | number | object
 }
 
 /**
@@ -183,12 +187,23 @@ export function parseScriptEnvelope(
   const rawResult = envelope.scriptResult
   let scriptResult: string | undefined
   let scriptError: string
+  let fmsMessage: string | undefined
 
-  if (rawResult !== null && typeof rawResult === 'object' && 'resultParameter' in rawResult) {
-    // Nested envelope (FMS v26+): code + resultParameter inside scriptResult
-    const nested = rawResult as { code?: unknown; resultParameter?: unknown }
+  if (
+    rawResult !== null &&
+    typeof rawResult === 'object' &&
+    ('code' in rawResult || 'resultParameter' in rawResult)
+  ) {
+    // Nested envelope (FMS v26+): code + resultParameter (+ message) inside scriptResult
+    const nested = rawResult as { code?: unknown; resultParameter?: unknown; message?: unknown }
     scriptError = nested.code !== undefined ? String(nested.code) : '0'
-    scriptResult = nested.resultParameter !== undefined ? String(nested.resultParameter) : undefined
+    scriptResult =
+      nested.resultParameter !== undefined
+        ? typeof nested.resultParameter === 'string'
+          ? nested.resultParameter
+          : JSON.stringify(nested.resultParameter)
+        : undefined
+    if (typeof nested.message === 'string') fmsMessage = nested.message
   } else {
     // Flat envelope (older FMS): scriptResult is a string, scriptError is a sibling
     scriptError = envelope.scriptError !== undefined ? String(envelope.scriptError) : '0'
@@ -202,7 +217,9 @@ export function parseScriptEnvelope(
 
   if (scriptError !== '0') {
     throw new FMScriptError(
-      `FileMaker script error ${scriptError}`,
+      fmsMessage
+        ? `FileMaker script error ${scriptError}: ${fmsMessage}`
+        : `FileMaker script error ${scriptError}`,
       {
         status: 200,
         scriptError,

package/src/webhooks.ts

@@ -0,0 +1,203 @@
+/**
+ * Webhook management for FileMaker Server OData.
+ *
+ * FMS exposes webhook management through five endpoints following the
+ * standard OData function-call shape: read endpoints use GET, and action
+ * endpoints use POST with the `<id>` passed as a function argument in the
+ * URL path.
+ *
+ *   GET  /<db>/Webhook.GetAll        — list all webhooks
+ *   GET  /<db>/Webhook.Get(<id>)     — get one webhook by id
+ *   POST /<db>/Webhook.Add           — create a webhook (config in JSON body)
+ *   POST /<db>/Webhook.Delete(<id>)  — delete a webhook (id in URL path)
+ *   POST /<db>/Webhook.Invoke(<id>)  — manually trigger a webhook (id in URL path)
+ *
+ * Webhooks require FileMaker Server 2025+ (v22). Use
+ * `db.hasFeature('webhooks')` to check before calling.
+ *
+ * @see https://github.com/fsans/fms-odata-spec/blob/main/docs/09-webhooks.md
+ */
+
+import type { WebhookCreateParams, WebhookData } from '@fms-odata/spec-ts'
+import type { FMSOData } from './client.js'
+import { executeJson } from './http.js'
+import type { RequestOptions } from './types.js'
+import { encodePathSegment } from './url.js'
+
+/** Options accepted by webhook operations. */
+export interface WebhookOptions extends RequestOptions {}
+
+/**
+ * Normalize create params: merge legacy `headers` into `endpointHeaders`
+ * (spec says `headers` is a legacy alias for `endpointHeaders`).
+ */
+function normalizeCreateParams(params: WebhookCreateParams): Record<string, unknown> {
+  const out: Record<string, unknown> = {
+    webhook: params.webhook,
+    tableName: params.tableName,
+  }
+  if (params.endpointHeaders) out.endpointHeaders = params.endpointHeaders
+  if (params.headers && !params.endpointHeaders) out.endpointHeaders = params.headers
+  if (params.queryHeaders) out.queryHeaders = params.queryHeaders
+  if (params.notifySchemaChanges !== undefined) out.notifySchemaChanges = params.notifySchemaChanges
+  if (params.select) out.select = params.select
+  if (params.filter) out.filter = params.filter
+  if (params.maxFailedAttempts !== undefined) out.maxFailedAttempts = params.maxFailedAttempts
+  return out
+}
+
+/**
+ * Extract the webhook ID from a `Webhook.Add` response.
+ *
+ * FMS returns `{ webhookResult: { webhookID: N } }`. Older or alternate
+ * shapes (`{ webhookID: N }`, `{ id: N }`) are accepted as fallbacks.
+ */
+function extractWebhookId(data: unknown): string | undefined {
+  if (!data || typeof data !== 'object') return undefined
+  const obj = data as Record<string, unknown>
+  const fromResult = obj.webhookResult as Record<string, unknown> | undefined
+  const id = fromResult?.webhookID ?? obj.webhookID ?? obj.id
+  return id !== undefined ? String(id) : undefined
+}
+
+/**
+ * Webhook manager for FileMaker Server webhook CRUD.
+ *
+ * Obtain an instance via `db.webhooks()` or use the convenience methods on
+ * `FMSOData` (`db.createWebhook`, `db.removeWebhook`, etc.).
+ *
+ * Requires FileMaker Server 2025+ (v22).
+ */
+export class WebhookManager {
+  /** @internal */ readonly _client: FMSOData
+
+  constructor(client: FMSOData) {
+    this._client = client
+  }
+
+  /** Build the URL for a webhook operation. */
+  private _url(operation: 'Add' | 'Delete' | 'Get' | 'GetAll' | 'Invoke', id?: string | number): string {
+    const base = `${this._client.baseUrl}/Webhook.${operation}`
+    return id !== undefined ? `${base}(${encodePathSegment(String(id))})` : base
+  }
+
+  /**
+   * Create a webhook.
+   *
+   * ```ts
+   * const { id } = await db.webhooks().create({
+   *   webhook: 'https://my.example.com:8080/webhook',
+   *   tableName: 'contact',
+   *   select: 'id,first_name',
+   *   filter: "status eq 'active'",
+   *   notifySchemaChanges: true,
+   * })
+   * ```
+   *
+   * @returns An object with the server-generated `id` of the new webhook.
+   */
+  async create(
+    params: WebhookCreateParams,
+    opts: WebhookOptions = {},
+  ): Promise<{ id: string }> {
+    if (!params.webhook) throw new TypeError('WebhookManager: `webhook` URL is required')
+    if (!params.tableName) throw new TypeError('WebhookManager: `tableName` is required')
+
+    const body = JSON.stringify(normalizeCreateParams(params))
+    const data = await executeJson<unknown>(this._client._ctx, this._url('Add'), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body,
+      accept: 'json',
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    })
+    const id = extractWebhookId(data)
+    if (id === undefined) {
+      throw new Error('WebhookManager: Webhook.Add did not return a webhook id')
+    }
+    return { id }
+  }
+
+  /**
+   * Delete a webhook by its ID.
+   *
+   * ```ts
+   * await db.webhooks().remove('1')
+   * ```
+   */
+  async remove(id: string | number, opts: WebhookOptions = {}): Promise<unknown> {
+    if (id === '' || id === undefined) throw new TypeError('WebhookManager: webhook `id` is required')
+    return executeJson<unknown>(this._client._ctx, this._url('Delete', id), {
+      method: 'POST',
+      accept: 'json',
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    })
+  }
+
+  /** Alias for {@link remove} (matches the FMS endpoint name `Webhook.Delete`). */
+  async delete(id: string | number, opts: WebhookOptions = {}): Promise<unknown> {
+    return this.remove(id, opts)
+  }
+
+  /**
+   * Get a specific webhook's data by ID.
+   *
+   * ```ts
+   * const data = await db.webhooks().get('1')
+   * ```
+   */
+  async get(id: string | number, opts: WebhookOptions = {}): Promise<WebhookData | unknown> {
+    if (id === '' || id === undefined) throw new TypeError('WebhookManager: webhook `id` is required')
+    return executeJson<unknown>(this._client._ctx, this._url('Get', id), {
+      method: 'GET',
+      accept: 'json',
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    })
+  }
+
+  /**
+   * List all webhooks.
+   *
+   * ```ts
+   * const result = await db.webhooks().getAll()
+   * ```
+   */
+  async getAll(opts: WebhookOptions = {}): Promise<unknown> {
+    return executeJson<unknown>(this._client._ctx, this._url('GetAll'), {
+      method: 'GET',
+      accept: 'json',
+      ...(opts.signal ? { signal: opts.signal } : {}),
+    })
+  }
+
+  /**
+   * Manually invoke (trigger) a webhook by ID. Useful for testing.
+   *
+   * Optionally pass `rowIDs` to target specific records; if omitted, FMS
+   * triggers the webhook for all pending records.
+   *
+   * ```ts
+   * await db.webhooks().invoke('1')
+   * await db.webhooks().invoke('1', { rowIDs: [10, 20] })
+   * ```
+   */
+  async invoke(
+    id: string | number,
+    opts: WebhookOptions & { rowIDs?: ReadonlyArray<string | number> } = {},
+  ): Promise<unknown> {
+    if (id === '' || id === undefined) throw new TypeError('WebhookManager: webhook `id` is required')
+    const { rowIDs, signal, ...rest } = opts
+    // FMS requires a JSON body for Invoke (it rejects empty bodies with a
+    // JSON syntax error). Send { rowIDs: [...] } — an empty array triggers
+    // the webhook for all pending records.
+    const body = JSON.stringify({ rowIDs: rowIDs ? [...rowIDs] : [] })
+    return executeJson<unknown>(this._client._ctx, this._url('Invoke', id), {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body,
+      accept: 'json',
+      ...(signal ? { signal } : {}),
+      ...rest,
+    })
+  }
+}