@object-ui/data-objectstack 15.0.0 → 16.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@object-ui/data-objectstack",
-  "version": "15.0.0",
+  "version": "16.1.0",
   "description": "ObjectStack Data Adapter for Object UI",
   "license": "MIT",
   "type": "module",
@@ -22,9 +22,9 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@objectstack/client": "^14.6.0",
-    "@object-ui/core": "15.0.0",
-    "@object-ui/types": "15.0.0"
+    "@objectstack/client": "^16.0.0-rc.0",
+    "@object-ui/core": "16.1.0",
+    "@object-ui/types": "16.1.0"
   },
   "devDependencies": {
     "tsup": "^8.5.1",

package/src/exportDownload.test.ts

@@ -23,7 +23,9 @@ function csvResponse(body = 'ID,Name\n1,Acme') {
 
 describe('ObjectStackAdapter.exportDownload', () => {
   it('GETs the /export route with format, fields, orderby, header and limit', async () => {
-    const fetchImpl = vi.fn(async () => csvResponse());
+    // Typed like `fetch` so `fetchImpl.mock.calls[0]` is `[url, init]` rather
+    // than an empty tuple (the zero-arg impl would otherwise infer `never`).
+    const fetchImpl = vi.fn(async (_url: string, _init: RequestInit) => csvResponse());
     const ds = makeDS(fetchImpl);
 
     const blob = await ds.exportDownload('task', {
@@ -50,7 +52,9 @@ describe('ObjectStackAdapter.exportDownload', () => {
   });
 
   it('defaults to csv and omits optional params when not provided', async () => {
-    const fetchImpl = vi.fn(async () => csvResponse());
+    // Typed like `fetch` so `fetchImpl.mock.calls[0]` is `[url, init]` rather
+    // than an empty tuple (the zero-arg impl would otherwise infer `never`).
+    const fetchImpl = vi.fn(async (_url: string, _init: RequestInit) => csvResponse());
     const ds = makeDS(fetchImpl);
 
     await ds.exportDownload('task', {});
@@ -65,7 +69,9 @@ describe('ObjectStackAdapter.exportDownload', () => {
   });
 
   it('serializes the filter to a JSON AST query param', async () => {
-    const fetchImpl = vi.fn(async () => csvResponse());
+    // Typed like `fetch` so `fetchImpl.mock.calls[0]` is `[url, init]` rather
+    // than an empty tuple (the zero-arg impl would otherwise infer `never`).
+    const fetchImpl = vi.fn(async (_url: string, _init: RequestInit) => csvResponse());
     const ds = makeDS(fetchImpl);
 
     await ds.exportDownload('task', { filter: [['status', '=', 'open']] });

package/src/index.ts

@@ -9,6 +9,7 @@
 import { ObjectStackClient, type QueryOptions as ObjectStackQueryOptions } from '@objectstack/client';
 import type {
   DataSource,
+  BatchTransactionOperation,
   MutationEvent,
   QueryParams,
   QueryResult,
@@ -23,8 +24,13 @@ import type {
   ImportJobUndoResult,
   ListImportJobsOptions,
 } from '@object-ui/types';
-import { convertFiltersToAST, normalizeSchemaReferenceKeys } from '@object-ui/core';
+import {
+  convertFiltersToAST,
+  emulateBatchTransaction,
+  normalizeSchemaReferenceKeys,
+} from '@object-ui/core';
 import { MetadataCache } from './cache/MetadataCache';
+import { MetadataClient } from './metadata-client';
 import {
   ObjectStackError,
   MetadataNotFoundError,
@@ -173,6 +179,44 @@ export function clearSharedDiscoveryCache(): void {
   discoveryCache.clear();
 }
 
+/**
+ * Read the cross-object atomic-batch capability from a `discovery` document
+ * (framework #3298 / objectui #2693). The server advertises it hierarchically
+ * under `capabilities.transactionalBatch.enabled`; the published
+ * `@objectstack/client` also accepts the flat `capabilities.transactionalBatch:
+ * boolean` form and normalizes the two — mirror that here so the adapter reads
+ * the same bit regardless of which shape reaches it.
+ *
+ * Returns:
+ *   - `true`  — the backend GUARANTEES an atomic `/batch` (declared === enforced,
+ *     i.e. the route is mounted AND the runtime can honour a transaction): the
+ *     client may drop its non-atomic fallback and treat any batch failure as a
+ *     real error.
+ *   - `false` — the backend explicitly does NOT (route absent, or a runtime that
+ *     can't open a transaction).
+ *   - `undefined` — the capability is absent, i.e. the backend predates #3298;
+ *     the caller must keep the legacy runtime-probe fallback (we can't tell
+ *     whether `/batch` exists without trying it).
+ */
+export function readTransactionalBatchCapability(
+  discovery: unknown,
+): boolean | undefined {
+  const caps = (discovery as { capabilities?: unknown } | null | undefined)?.capabilities;
+  if (!caps || typeof caps !== 'object') return undefined;
+  const value = (caps as Record<string, unknown>).transactionalBatch;
+  // Flat form: `{ transactionalBatch: true }`.
+  if (typeof value === 'boolean') return value;
+  // Hierarchical form: `{ transactionalBatch: { enabled: true } }`.
+  if (
+    value &&
+    typeof value === 'object' &&
+    typeof (value as { enabled?: unknown }).enabled === 'boolean'
+  ) {
+    return (value as { enabled: boolean }).enabled;
+  }
+  return undefined;
+}
+
 /**
  * Detect "missing resource" errors regardless of where they originate.
  *
@@ -404,6 +448,21 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
   // so optional collections like sys_presence don't hammer the server with
   // failing requests on every record open / panel render.
   private missingResources = new Set<string>();
+  // Set once the server has told us it can't do a cross-object transactional
+  // batch (the client SDK's data.batchTransaction threw HTTP 404/405/501). After
+  // that, batchTransaction skips the SDK call and serves every call via the
+  // client-side emulation — the non-atomic fallback lives HERE, isolated to the
+  // one adapter that has to cope with a backend lacking server atomicity (#2679).
+  private batchUnsupported = false;
+  // The server's declared cross-object atomic-batch capability, read from
+  // discovery at connect() (framework #3298 / objectui #2693). `true` → the
+  // backend GUARANTEES an atomic `/batch`, so batchTransaction trusts it and
+  // never degrades to the non-atomic emulation (any failure surfaces as a real
+  // error). `false` or `undefined` (capability absent → backend predates #3298)
+  // → keep the legacy runtime-probe + emulation fallback so a save is still
+  // possible; dropping it there would turn "saves, less safe" into "no save
+  // path" on older backends (#2679 compatibility constraint).
+  private atomicBatchCapability: boolean | undefined;
   // Subscribers registered via onMutation(). Emitted after each successful
   // create/update/delete so data-bound views (ListView, ObjectView, kanban,
   // calendar) auto-refresh — the interface ListView relies on to reflect
@@ -479,6 +538,11 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         // helpers continue to work without a redundant fetch.
         (this.client as unknown as { discoveryInfo?: unknown }).discoveryInfo = data;
 
+        // Record the declared cross-object atomic-batch capability (#3298) so
+        // batchTransaction can decide declaratively at call time whether it may
+        // trust server atomicity instead of runtime-probing 404/405/501.
+        this.atomicBatchCapability = readTransactionalBatchCapability(data);
+
         this.connected = true;
         this.reconnectAttempts = 0;
         this.setConnectionState('connected');
@@ -927,42 +991,119 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
    * @returns Promise resolving to array of results
    */
   /**
-   * Cross-object transactional batch (ObjectStack #1604). Runs the operations
-   * in ONE server transaction — commit all or roll back all. A field value of
-   * `{ $ref: <earlier op index> }` resolves to that op's created id, so a child
-   * can reference its parent created earlier in the same batch (master-detail).
+   * Cross-object transactional batch (ObjectStack #1604 / ADR-0034 item 4).
+   * Runs the operations in ONE server transaction — commit all or roll back
+   * all. A field value of `{ $ref: <earlier op index> }` resolves to that op's
+   * created id, so a child can reference its parent created earlier in the same
+   * batch (master-detail).
+   *
+   * Transport: the published `@objectstack/client` SDK method
+   * `data.batchTransaction` (framework #3271; shipped since client v16, our
+   * dependency floor). Per AGENTS.md §7 data always flows through the client —
+   * never a hand-rolled `fetch('/api/v1/batch')`.
+   *
+   * Fallback decision — declarative capability negotiation (framework #3298 /
+   * objectui #2693). At connect() we read `capabilities.transactionalBatch`
+   * from discovery:
+   *   - Declared `true` → the backend GUARANTEES atomicity (declared ===
+   *     enforced). We TRUST it: any batch failure — including 404/405/501 —
+   *     surfaces as a real error. No non-atomic client-side compensation. This
+   *     is the path modern backends take.
+   *   - Declared `false`, or ABSENT (backend predates #3298) → we can't rely on
+   *     server atomicity, so we keep the legacy behaviour: on 404/405 (no
+   *     endpoint) or 501 (runtime without transactions) degrade to the
+   *     client-side, NON-atomic {@link emulateBatchTransaction} so a save is
+   *     still possible. Removing that here would regress older backends from
+   *     "saves, less safe" to "no save path" (#2679 compatibility constraint).
+   *     The non-atomic fallback stays isolated to THIS adapter.
    */
   async batchTransaction(
-    operations: Array<{ object: string; action?: 'create' | 'update' | 'delete'; data?: any; id?: string }>,
+    operations: BatchTransactionOperation[],
   ): Promise<{ results: any[] }> {
-    const url = `${this.baseUrl}/api/v1/batch`;
-    const response = await this.fetchImpl(url, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json', ...this.getAuthHeaders() },
-      // Send the session cookie too: in the browser console auth is cookie-based
-      // (no bearer `token`), so without `credentials: 'include'` this raw fetch
-      // is unauthenticated — every master-detail batch save would 401. Bearer
-      // (server-to-server) and cookie (console) auth now both work.
-      credentials: 'include',
-      body: JSON.stringify({ operations }),
-    });
-    if (!response.ok) {
-      const error = await response.json().catch(() => ({ message: response.statusText }));
-      throw new ObjectStackError(
-        error.error || error.message || `Batch failed with status ${response.status}`,
-        'BATCH_ERROR',
-        response.status,
+    // Ensure discovery (and thus the #3298 capability) is loaded so the
+    // decision below is declarative, not "fire a batch and read the status".
+    await this.connect();
+
+    // When the backend declares atomic batch support we never degrade: a
+    // failure is a real error, not a cue to fall back. Otherwise (declared
+    // false, or capability absent on a pre-#3298 backend) the emulation
+    // fallback below stays active.
+    const guaranteed = this.atomicBatchCapability === true;
+
+    // Already degraded on a non-declaring backend — skip the SDK call.
+    // (Unreachable once `guaranteed`: that path never sets `batchUnsupported`.)
+    if (!guaranteed && this.batchUnsupported) {
+      return emulateBatchTransaction(this, operations);
+    }
+
+    try {
+      // Typed SDK method — guaranteed present by the `@objectstack/client@^16`
+      // dependency floor (framework #3271). No hand-rolled POST /api/v1/batch.
+      const payload = await this.client.data.batchTransaction(operations);
+      this.emitBatchMutations(operations, payload?.results);
+      return payload;
+    } catch (err) {
+      // On a non-declaring backend, endpoint missing (404/405) or a runtime that
+      // can't do transactions (the framework rest-server answers 501
+      // "Transactional batch not supported by this runtime") → degrade to the
+      // non-atomic client emulation so the save still goes through. When the
+      // backend DECLARED support (`guaranteed`), even these are hard errors — a
+      // server that advertised the capability must honour it. Every other status
+      // (400 validation, 401/403 auth, 409 conflict, 500 fault) is a real error
+      // the caller must see — never silently retried.
+      const status = this.errorStatusOf(err);
+      if (!guaranteed && this.batchStatusUnsupported(status)) {
+        return this.fallbackToEmulation(operations, status);
+      }
+      throw err;
+    }
+  }
+
+  /** True for statuses that mean "this backend can't do a transactional batch". */
+  private batchStatusUnsupported(status: number | undefined): boolean {
+    return status === 404 || status === 405 || status === 501;
+  }
+
+  /** Best-effort HTTP status extraction from a thrown SDK/client error. */
+  private errorStatusOf(err: unknown): number | undefined {
+    if (!err || typeof err !== 'object') return undefined;
+    const e = err as Record<string, unknown>;
+    const s = e.httpStatus ?? e.status ?? e.statusCode;
+    return typeof s === 'number' ? s : undefined;
+  }
+
+  /** Mark the endpoint unsupported (warn once) and serve via emulation. */
+  private fallbackToEmulation(
+    operations: BatchTransactionOperation[],
+    status: number | undefined,
+  ): Promise<{ results: any[] }> {
+    if (!this.batchUnsupported) {
+      this.batchUnsupported = true;
+      console.warn(
+        `ObjectStackAdapter: POST /api/v1/batch unavailable (HTTP ${status ?? '?'}) — ` +
+          'falling back to non-atomic client-side batch emulation. Cross-object ' +
+          'saves on this backend are best-effort, not transactional.',
       );
     }
-    const payload: { results: any[] } = await response.json();
-    // The whole transaction committed — emit one MutationEvent per operation so
-    // the invalidation bus (#2269) sees writes that went through /batch exactly
-    // like single create/update/delete calls (master-detail ModalForm saves
-    // otherwise leave related lists and count badges stale, #2582). `results`
-    // is index-aligned with `operations`; creates take id/record from the
-    // server echo. A failed batch rolled back entirely and throws above, so
-    // nothing is emitted for it.
-    const results = Array.isArray(payload?.results) ? payload.results : [];
+    return emulateBatchTransaction(this, operations);
+  }
+
+  /**
+   * Emit one MutationEvent per committed operation so the invalidation bus
+   * (#2269) sees writes that went through /batch exactly like single
+   * create/update/delete calls — master-detail ModalForm saves otherwise leave
+   * related lists and count badges stale (#2582). `results` is index-aligned
+   * with `operations`; creates take id/record from the server echo.
+   *
+   * Only called on the server-committed paths. The emulation branch drives the
+   * adapter's own create/update/delete primitives, which already emit — so it
+   * must NOT be routed through here, or events would double-fire.
+   */
+  private emitBatchMutations(
+    operations: BatchTransactionOperation[],
+    rawResults: unknown,
+  ): void {
+    const results = Array.isArray(rawResults) ? rawResults : [];
     operations.forEach((op, i) => {
       const action = op.action ?? 'create';
       const echo = results[i];
@@ -974,7 +1115,6 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         this.emitMutation({ type: 'delete', resource: op.object, id: op.id });
       }
     });
-    return payload;
   }
 
   async bulk(resource: string, operation: 'create' | 'update' | 'delete', data: Partial<T>[]): Promise<T[]> {
@@ -1930,32 +2070,25 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     config: Record<string, any>
   ): Promise<Record<string, any> | void> {
     await this.connect();
-    try {
-      // ADR-0005 metadata customization overlay: persist views under
-      // `type='view'` (NOT `type=<objectName>` — that was a pre-overlay
-      // misuse that hit `/api/v1/meta/<objectName>/<viewId>`, which the
-      // server never wired). The view's `data.object` field is what
-      // associates it back to the object on read.
-      const merged = { ...(config || {}), object: (config as any)?.object || objectName, name: viewId };
-      const result: any = await this.client.meta.saveItem(
-        'view',
-        viewId,
-        merged
-      );
-      // Invalidate cached read so next getView reflects the change
-      const cacheKey = `view:${objectName}:${viewId}`;
-      this.metadataCache.invalidate?.(cacheKey);
-      // Also invalidate the batch override map so listViewOverrides re-fetches
-      this.metadataCache.invalidate?.(`view-overrides:${objectName}`);
-      this.metadataCache.invalidate?.(`views:${objectName}`);
-      if (result && result.item) return result.item;
-      return result ?? undefined;
-    } catch (err) {
-      // Surface the error so the caller can decide whether to toast/log;
-      // we don't swallow it here because persistence failures are
-      // operationally meaningful (unlike read fallbacks).
-      throw err;
-    }
+    // ADR-0005 metadata customization overlay: persist views under
+    // `type='view'` (NOT `type=<objectName>` — that was a pre-overlay
+    // misuse that hit `/api/v1/meta/<objectName>/<viewId>`, which the
+    // server never wired). The view's `data.object` field is what
+    // associates it back to the object on read.
+    const merged = { ...(config || {}), object: (config as any)?.object || objectName, name: viewId };
+    const result: any = await this.client.meta.saveItem(
+      'view',
+      viewId,
+      merged
+    );
+    // Invalidate cached read so next getView reflects the change
+    const cacheKey = `view:${objectName}:${viewId}`;
+    this.metadataCache.invalidate?.(cacheKey);
+    // Also invalidate the batch override map so listViewOverrides re-fetches
+    this.metadataCache.invalidate?.(`view-overrides:${objectName}`);
+    this.metadataCache.invalidate?.(`views:${objectName}`);
+    if (result && result.item) return result.item;
+    return result ?? undefined;
   }
 
   /**
@@ -1968,13 +2101,31 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
    * Filters by `data.object === objectName` (or top-level `object`)
    * client-side because the metadata index is name-only, not field-typed.
    */
-  async listViews(objectName: string): Promise<any[]> {
+  async listViews(
+    objectName: string,
+    options?: { previewDrafts?: boolean },
+  ): Promise<any[]> {
     await this.connect();
     try {
-      const result: any = await this.client.meta.getItems('view');
-      const items: any[] = Array.isArray(result?.items)
-        ? result.items
-        : Array.isArray(result) ? result : [];
+      let items: any[];
+      if (options?.previewDrafts) {
+        // ADR-0037 + #2767 (P2/P3): a SINGLE `?preview=draft` request already
+        // returns the active+draft OVERLAID list — draft wins by name,
+        // draft-only views surface, each draft tagged `_draft: true`. So we
+        // REPLACE the published list wholesale (never fetch both and append,
+        // which double-lists a draft that edits a published view). Route it
+        // through `MetadataClient` rather than a hand-rolled fetch so the
+        // metadata route + any environment scoping stay in one place.
+        const draftItems = await this.metadataClient()
+          .withPreviewDrafts(true)
+          .list<any>('view');
+        items = Array.isArray(draftItems) ? draftItems : [];
+      } else {
+        const result: any = await this.client.meta.getItems('view');
+        items = Array.isArray(result?.items)
+          ? result.items
+          : Array.isArray(result) ? result : [];
+      }
       // This feeds the list-view switcher (ViewTabBar), so it must return
       // LIST-family views only. The backend now exposes each view as an
       // independent ViewItem carrying a `viewKind` discriminant (ADR-0017);
@@ -1993,6 +2144,10 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
         return !(viewKind && FORM_FAMILY.has(viewKind));
       }).map((v: any) => {
         const spec = v.list ?? v;
+        // Preserve the draft provenance flag so the switcher can badge an
+        // unpublished view (ADR-0037). The overlay tags the item, not its
+        // nested spec, so read from either.
+        const isDraft = v._draft === true || spec?._draft === true;
         // Canonical ViewItem (ADR-0017) carries its body under `config`;
         // the display `type` (grid/kanban/gallery/…) lives at `config.type`,
         // and only the list/form *family* sits at the top level (`viewKind`).
@@ -2008,9 +2163,10 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
             name: spec.name ?? spec.config.name,
             label: spec.label ?? spec.config.label,
             isDefault: !!spec.isDefault,
+            ...(isDraft ? { _draft: true } : {}),
           };
         }
-        return spec;
+        return isDraft ? { ...spec, _draft: true } : spec;
       });
     } catch (err) {
       console.warn('[OBJECTSTACKDataSource] listViews failed:', err);
@@ -2018,6 +2174,20 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     }
   }
 
+  /**
+   * Build a {@link MetadataClient} bound to this adapter's server + auth. Used
+   * by draft-aware reads (`listViews({ previewDrafts })`) so the `/meta` route,
+   * `?preview=draft` flag, and environment scoping live in the SDK rather than
+   * being hand-assembled at each call site (#2767 P3).
+   */
+  private metadataClient(): MetadataClient {
+    return new MetadataClient({
+      baseUrl: this.baseUrl,
+      fetch: this.fetchImpl,
+      ...(this.token ? { headers: { Authorization: `Bearer ${this.token}` } } : {}),
+    });
+  }
+
   /**
    * List registered import `mapping` artifacts targeting a given object
    * (framework #2611). Reads the `mapping` metadata kind via the overlay API
@@ -2075,14 +2245,10 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       object: spec?.object || objectName,
       data: spec?.data || { provider: 'object', object: objectName },
     };
-    try {
-      const result: any = await this.client.meta.saveItem('view', name, fullSpec);
-      this.metadataCache.invalidate?.(`views:${objectName}`);
-      if (result && result.item) return result.item;
-      return fullSpec;
-    } catch (err) {
-      throw err;
-    }
+    const result: any = await this.client.meta.saveItem('view', name, fullSpec);
+    this.metadataCache.invalidate?.(`views:${objectName}`);
+    if (result && result.item) return result.item;
+    return fullSpec;
   }
 
   /**
@@ -2112,15 +2278,11 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
       name: viewName,
       object: current?.object || (current as any)?.data?.object || objectName,
     };
-    try {
-      const result: any = await this.client.meta.saveItem('view', viewName, merged);
-      this.metadataCache.invalidate?.(`views:${objectName}`);
-      this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
-      if (result && result.item) return result.item;
-      return merged;
-    } catch (err) {
-      throw err;
-    }
+    const result: any = await this.client.meta.saveItem('view', viewName, merged);
+    this.metadataCache.invalidate?.(`views:${objectName}`);
+    this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
+    if (result && result.item) return result.item;
+    return merged;
   }
 
   /**
@@ -2133,14 +2295,10 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     viewName: string,
   ): Promise<{ deleted: boolean }> {
     await this.connect();
-    try {
-      const result: any = await this.client.meta.deleteItem('view', viewName);
-      this.metadataCache.invalidate?.(`views:${objectName}`);
-      this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
-      return { deleted: !!(result?.deleted ?? result?.reset ?? true) };
-    } catch (err) {
-      throw err;
-    }
+    const result: any = await this.client.meta.deleteItem('view', viewName);
+    this.metadataCache.invalidate?.(`views:${objectName}`);
+    this.metadataCache.invalidate?.(`view:${objectName}:${viewName}`);
+    return { deleted: !!(result?.deleted ?? result?.reset ?? true) };
   }
 
 
@@ -2207,21 +2365,17 @@ export class ObjectStackAdapter<T = unknown> implements DataSource<T> {
     schema: Record<string, any>
   ): Promise<Record<string, any> | void> {
     await this.connect();
-    try {
-      const result: any = await this.client.meta.saveItem(
-        'dashboard',
-        dashboardName,
-        schema
-      );
-      // Invalidate dashboards list and any cached dashboard read so the
-      // next render reflects the change.
-      this.metadataCache.invalidate?.('dashboards');
-      this.metadataCache.invalidate?.(`dashboard:${dashboardName}`);
-      if (result && result.item) return result.item;
-      return result ?? undefined;
-    } catch (err) {
-      throw err;
-    }
+    const result: any = await this.client.meta.saveItem(
+      'dashboard',
+      dashboardName,
+      schema
+    );
+    // Invalidate dashboards list and any cached dashboard read so the
+    // next render reflects the change.
+    this.metadataCache.invalidate?.('dashboards');
+    this.metadataCache.invalidate?.(`dashboard:${dashboardName}`);
+    if (result && result.item) return result.item;
+    return result ?? undefined;
   }
 
   /**

package/src/integration.ts

@@ -143,6 +143,10 @@ export class IntegrationManager {
           }
         } catch (e) {
           if (e instanceof TypeError) {
+            // A malformed URL surfaces as its own message; we can't attach `e`
+            // as the `Error` `cause` because this package targets ES2020, whose
+            // lib types the 1-arg `Error` constructor only. Scoped disable.
+            // eslint-disable-next-line preserve-caught-error
             throw new Error(`Invalid webhook URL: ${url}`);
           }
           throw e;
@@ -168,6 +172,10 @@ export class IntegrationManager {
           }
         } catch (e) {
           if (e instanceof TypeError) {
+            // A malformed URL surfaces as its own message; we can't attach `e`
+            // as the `Error` `cause` because this package targets ES2020, whose
+            // lib types the 1-arg `Error` constructor only. Scoped disable.
+            // eslint-disable-next-line preserve-caught-error
             throw new Error(`Invalid Slack webhook URL: ${url}`);
           }
           throw e;