@metabase/client 0.0.0-stage → 0.1.0

package/dist/resources/metric.js

@@ -0,0 +1,50 @@
+import { CardQueryResult } from "../domain/card.js";
+import { t as explainer } from "../refusal-B9aeHMc9.js";
+import { MetricBreakoutValues, MetricDimensionListing } from "../domain/metric.js";
+//#region src/resources/metric.ts
+function metricResource(transport) {
+	const { explain } = explainer(transport, "metric");
+	/**
+	* Run a metric definition and return the query result envelope: one metric or measure, or an
+	* arithmetic expression over several, each leaf filtered and projected on its own `lib/uuid`.
+	*/
+	async function query(definition, options = {}) {
+		return transport.requestParsed(CardQueryResult, "/api/metric/dataset", {
+			...options,
+			method: "POST",
+			body: { definition }
+		});
+	}
+	/**
+	* Fetch the distinct values of a definition's breakout dimension, with that column's metadata.
+	* Takes the same definition `query` does.
+	*/
+	async function breakoutValues(definition, options = {}) {
+		return transport.requestParsed(MetricBreakoutValues, "/api/metric/breakout-values", {
+			...options,
+			method: "POST",
+			body: { definition }
+		});
+	}
+	/**
+	* List a metric's curated dimensions and, under `with-addable`, the columns still available to
+	* add, grouped by source table. `query` filters both by a name substring.
+	*/
+	async function dimensions(id, params = {}, options = {}) {
+		return transport.requestParsed(MetricDimensionListing, `/api/metric/${id}/dimension`, {
+			...options,
+			query: {
+				query: params.query,
+				"with-addable": params["with-addable"],
+				"include-orphaned": params["include-orphaned"]
+			}
+		});
+	}
+	return {
+		query: explain("query", query),
+		breakoutValues: explain("breakoutValues", breakoutValues),
+		dimensions: explain("dimensions", dimensions)
+	};
+}
+//#endregion
+export { metricResource };

package/dist/resources/moderation-review.d.ts

@@ -0,0 +1,23 @@
+import { f as RequestOptions, h as Transport } from "../transport-E0ZaPNWJ.js";
+//#region src/resources/moderation-review.d.ts
+declare function moderationReviewResource(transport: Transport): {
+  create: (params: {
+    moderated_item_id: number;
+    moderated_item_type: "card" | "dashboard";
+    status?: "verified" | null | undefined;
+    text?: string | null | undefined;
+  }, options?: RequestOptions | undefined) => Promise<{
+    [x: string]: unknown;
+    id: number;
+    moderated_item_id: number;
+    moderated_item_type: "card" | "dashboard";
+    moderator_id: number;
+    status: "verified" | null;
+    text: string | null;
+    most_recent: boolean;
+    created_at: string;
+    updated_at: string;
+  }>;
+};
+//#endregion
+export { moderationReviewResource };

package/dist/resources/moderation-review.js

@@ -0,0 +1,24 @@
+import { ModerationReview, ModerationReviewCreateInput } from "../domain/moderation-review.js";
+import { t as explainer } from "../refusal-B9aeHMc9.js";
+import { parseRequestBody } from "./request-body.js";
+//#region src/resources/moderation-review.ts
+function moderationReviewResource(transport) {
+	const { explain } = explainer(transport, "moderationReview");
+	/**
+	* Create a moderation review on a card or dashboard. `status: "verified"` marks the item
+	* verified, `null` or an absent status records a note that leaves it unverified. The new review
+	* becomes the item's most recent one; the server keeps the ten newest per item. Admins only.
+	* A body that does not match `ModerationReviewCreateInput` is refused before any request.
+	*/
+	async function create(params, options = {}) {
+		const body = parseRequestBody(ModerationReviewCreateInput, params, "moderation review");
+		return transport.requestParsed(ModerationReview, "/api/moderation-review", {
+			...options,
+			method: "POST",
+			body
+		});
+	}
+	return { create: explain("create", create) };
+}
+//#endregion
+export { moderationReviewResource };

package/dist/resources/notification.d.ts

@@ -0,0 +1,2 @@
+import { i as notificationResource, n as assertCardAlert, r as mergeAlertUpdate, t as NotificationListParams } from "../notification-BiegPoSD.js";
+export { NotificationListParams, assertCardAlert, mergeAlertUpdate, notificationResource };

package/dist/resources/notification.js

@@ -0,0 +1,93 @@
+import { ConfigError } from "../errors.js";
+import { CARD_PAYLOAD_TYPE, Notification, NotificationCardPayload } from "../domain/notification.js";
+import { z } from "zod";
+//#region src/resources/notification.ts
+const NotificationApiList = z.array(Notification);
+function assertCardAlert(notification) {
+	if (notification.payload_type !== "notification/card") throw new ConfigError(`notification ${notification.id} is a ${notification.payload_type}, not a question alert — this operation accepts card alerts only`);
+	return notification;
+}
+function mergeAlertUpdate(current, patch) {
+	return Notification.parse({
+		...current,
+		...patch,
+		id: current.id,
+		payload: patch.payload === void 0 ? current.payload : mergePayload(current, patch.payload)
+	});
+}
+function mergePayload(current, patch) {
+	if (current.payload === null) throw new ConfigError(`alert ${current.id} has lost its card payload — it can be archived, but not patched`);
+	return NotificationCardPayload.parse({
+		...current.payload,
+		...patch
+	});
+}
+function notificationResource(transport) {
+	/**
+	* List question alerts, optionally narrowed by the card they watch, their creator, or a
+	* recipient. `/api/notification` also serves Metabase's internal system-event notifications, so
+	* the request pins the card payload type.
+	*/
+	async function list(params = {}, options = {}) {
+		return {
+			data: await transport.requestParsed(NotificationApiList, "/api/notification", {
+				...options,
+				query: {
+					payload_type: CARD_PAYLOAD_TYPE,
+					card_id: params.card_id,
+					creator_id: params.creator_id,
+					recipient_id: params.recipient_id,
+					include_inactive: params.include_inactive
+				}
+			}),
+			total: null
+		};
+	}
+	/** Get one question alert by id, refusing an id that names a system-event notification. */
+	async function get(id, options = {}) {
+		return assertCardAlert(await transport.requestParsed(Notification, `/api/notification/${id}`, { ...options }));
+	}
+	/** Create a question alert — its card payload, schedules and handlers — from a full body. */
+	async function create(params, options = {}) {
+		return transport.requestParsed(Notification, "/api/notification", {
+			...options,
+			method: "POST",
+			body: params
+		});
+	}
+	/** Update a question alert by id, merging the patch over the stored notification. */
+	async function update(id, params, options = {}) {
+		const current = await get(id, options);
+		return transport.requestParsed(Notification, `/api/notification/${id}`, {
+			...options,
+			method: "PUT",
+			body: mergeAlertUpdate(current, params)
+		});
+	}
+	/** Archive a question alert by id, stopping every delivery. Metabase models this as an update. */
+	async function archive(id, options = {}) {
+		return update(id, { active: false }, options);
+	}
+	/**
+	* Send a question alert now, off-schedule, to every handler on it. The server answers with no
+	* body.
+	*/
+	async function send(id, options = {}) {
+		await get(id, options);
+		await transport.requestRaw(`/api/notification/${id}/send`, {
+			...options,
+			method: "POST",
+			expectContentType: "binary"
+		});
+	}
+	return {
+		list,
+		get,
+		create,
+		update,
+		archive,
+		send
+	};
+}
+//#endregion
+export { assertCardAlert, mergeAlertUpdate, notificationResource };

package/dist/resources/optional-parsed.d.ts

@@ -0,0 +1,7 @@
+import { f as RequestOptions, g as TransportRequestOptions, h as Transport } from "../transport-E0ZaPNWJ.js";
+import { ZodType } from "zod";
+//#region src/resources/optional-parsed.d.ts
+type OptionalParsedOptions = RequestOptions & Pick<TransportRequestOptions, "query">;
+declare function fetchOptionalParsed<T>(client: Transport, path: string, schema: ZodType<T>, options?: OptionalParsedOptions): Promise<T | null>;
+//#endregion
+export { OptionalParsedOptions, fetchOptionalParsed };

package/dist/resources/optional-parsed.js

@@ -0,0 +1,14 @@
+import { parseJsonOrPlain } from "../json.js";
+//#region src/resources/optional-parsed.ts
+const NO_CONTENT_STATUS = 204;
+async function fetchOptionalParsed(client, path, schema, options = {}) {
+	const response = await client.requestRaw(path, {
+		...options,
+		method: "GET",
+		expectContentType: "binary"
+	});
+	if (response.status === NO_CONTENT_STATUS) return null;
+	return parseJsonOrPlain(await response.text(), response.headers.get("content-type"), schema, { source: response.url });
+}
+//#endregion
+export { fetchOptionalParsed };

package/dist/resources/permission.d.ts

@@ -0,0 +1,10 @@
+import { f as RequestOptions, h as Transport } from "../transport-E0ZaPNWJ.js";
+import { a as PermissionsGraph } from "../permission-BnCQw5Kp.js";
+//#region src/resources/permission.d.ts
+declare function permissionResource(transport: Transport): {
+  graph: (options?: RequestOptions) => Promise<PermissionsGraph>;
+  databaseGraph: (id: number, options?: RequestOptions) => Promise<PermissionsGraph>;
+  groupGraph: (id: number, options?: RequestOptions) => Promise<PermissionsGraph>;
+};
+//#endregion
+export { permissionResource };

package/dist/resources/permission.js

@@ -0,0 +1,31 @@
+import { PermissionsGraph } from "../domain/permission.js";
+//#region src/resources/permission.ts
+function permissionResource(transport) {
+	/**
+	* Get the data permissions of every group on every database, keyed by group id then database
+	* id. Admin only. One read of the whole `data_permissions` table, so prefer `databaseGraph` when
+	* one database is the question.
+	*/
+	async function graph(options = {}) {
+		return transport.requestParsed(PermissionsGraph, "/api/permissions/graph", { ...options });
+	}
+	/**
+	* Get the data permissions of every group on one database. Admin only. The read is filtered to
+	* that database, so this is the cheapest way to learn which groups can query a table: look the
+	* group up under the database and read `view-data` and `create-queries` down to the table id.
+	*/
+	async function databaseGraph(id, options = {}) {
+		return transport.requestParsed(PermissionsGraph, `/api/permissions/graph/db/${id}`, { ...options });
+	}
+	/** Get the data permissions of one group on every database. Admin only. */
+	async function groupGraph(id, options = {}) {
+		return transport.requestParsed(PermissionsGraph, `/api/permissions/graph/group/${id}`, { ...options });
+	}
+	return {
+		graph,
+		databaseGraph,
+		groupGraph
+	};
+}
+//#endregion
+export { permissionResource };

package/dist/resources/pivot-export.d.ts

@@ -0,0 +1,10 @@
+import { n as ExportFormat } from "../query-Xsin530u.js";
+import { f as RequestOptions, h as Transport } from "../transport-E0ZaPNWJ.js";
+//#region src/resources/pivot-export.d.ts
+/**
+ * Refuse a pivoted export the server would answer with plain rows: a JSON export keeps only the
+ * ungrouped rows, and an admin can turn pivoted CSV and XLSX exports off.
+ */
+declare function assertPivotedExport(transport: Transport, format: ExportFormat, options: RequestOptions): Promise<void>;
+//#endregion
+export { assertPivotedExport };

package/dist/resources/pivot-export.js

@@ -0,0 +1,16 @@
+import { SessionProperties } from "../domain/session-properties.js";
+import { ConfigError } from "../errors.js";
+import { PivotExportFormat } from "../domain/query.js";
+import { z } from "zod";
+//#region src/resources/pivot-export.ts
+const PivotedExportsProperty = SessionProperties.extend({ "enable-pivoted-exports": z.boolean() });
+/**
+* Refuse a pivoted export the server would answer with plain rows: a JSON export keeps only the
+* ungrouped rows, and an admin can turn pivoted CSV and XLSX exports off.
+*/
+async function assertPivotedExport(transport, format, options) {
+	if (!PivotExportFormat.safeParse(format).success) throw new ConfigError(`a ${format} export cannot be pivoted; only ${PivotExportFormat.options.join(" and ")} can`);
+	if (!(await transport.probe(PivotedExportsProperty, options))["enable-pivoted-exports"]) throw new ConfigError("the server has pivoted exports turned off (the enable-pivoted-exports setting), so it would export the plain rows");
+}
+//#endregion
+export { assertPivotedExport };

package/dist/resources/pulse.d.ts

@@ -0,0 +1,2 @@
+import { n as mergePulseUpdate, r as pulseResource, t as PulseListParams } from "../pulse-dylocLd9.js";
+export { PulseListParams, mergePulseUpdate, pulseResource };

package/dist/resources/pulse.js

@@ -0,0 +1,75 @@
+import { Pulse } from "../domain/pulse.js";
+import { z } from "zod";
+//#region src/resources/pulse.ts
+const PulseApiList = z.array(Pulse);
+function mergePulseUpdate(current, patch) {
+	return {
+		...patch,
+		archived: patch.archived ?? current.archived,
+		skip_if_empty: patch.skip_if_empty ?? current.skip_if_empty
+	};
+}
+function pulseResource(transport) {
+	/** List dashboard subscriptions, optionally narrowed to one dashboard or to the archived ones. */
+	async function list(params = {}, options = {}) {
+		return {
+			data: await transport.requestParsed(PulseApiList, "/api/pulse", {
+				...options,
+				query: {
+					dashboard_id: params.dashboard_id,
+					archived: params.archived
+				}
+			}),
+			total: null
+		};
+	}
+	/** Get one dashboard subscription by id. */
+	async function get(id, options = {}) {
+		return transport.requestParsed(Pulse, `/api/pulse/${id}`, { ...options });
+	}
+	/**
+	* Create a dashboard subscription — its cards and its delivery channels — from a full body.
+	* Non-empty `parameters` need the `dashboard_subscription_filters` premium feature, and are
+	* refused before the wire without it.
+	*/
+	async function create(params, options = {}) {
+		await requireSubscriptionFilters(params.parameters, options);
+		return transport.requestParsed(Pulse, "/api/pulse", {
+			...options,
+			method: "POST",
+			body: params
+		});
+	}
+	/**
+	* Update a dashboard subscription by id, carrying the server-defaulted flags forward. Non-empty
+	* `parameters` are refused as on `create`.
+	*/
+	async function update(id, params, options = {}) {
+		await requireSubscriptionFilters(params.parameters, options);
+		const current = await get(id, options);
+		return transport.requestParsed(Pulse, `/api/pulse/${id}`, {
+			...options,
+			method: "PUT",
+			body: mergePulseUpdate(current, params)
+		});
+	}
+	/**
+	* Archive a dashboard subscription by id, stopping every delivery. Metabase models this as an
+	* update, and disables each of the subscription's channels as a side effect.
+	*/
+	async function archive(id, options = {}) {
+		return update(id, { archived: true }, options);
+	}
+	async function requireSubscriptionFilters(parameters, options) {
+		if (parameters !== void 0 && parameters.length > 0) await transport.requireFeatures(["dashboardSubscriptionFilters"], options);
+	}
+	return {
+		list,
+		get,
+		create,
+		update,
+		archive
+	};
+}
+//#endregion
+export { mergePulseUpdate, pulseResource };

package/dist/resources/replacement.d.ts

@@ -0,0 +1,2 @@
+import { n as replacementResource, t as ReplacementRunListParams } from "../replacement-S9U3gApY.js";
+export { ReplacementRunListParams, replacementResource };

package/dist/resources/replacement.js

@@ -0,0 +1,82 @@
+import { t as explainer } from "../refusal-B9aeHMc9.js";
+import { ReplacementCheck, ReplacementRun, ReplacementRunStarted } from "../domain/replacement.js";
+import { z } from "zod";
+//#region src/resources/replacement.ts
+const ReplacementApiRunList = z.array(ReplacementRun);
+const CancelRunResponse = z.object({ success: z.literal(true) });
+function replacementResource(transport) {
+	const { explain } = explainer(transport, "replacement");
+	/**
+	* Check whether every usage of a source entity could be rewritten to read a target entity
+	* instead: the two must share a database, the target must not depend on the source, every source
+	* column must exist on the target with a compatible type, and a table source must not be joined
+	* implicitly or sandboxed. Admins only.
+	*/
+	async function checkReplaceSource(params, options = {}) {
+		return transport.requestParsed(ReplacementCheck, "/api/ee/replacement/check-replace-source", {
+			...options,
+			method: "POST",
+			body: params
+		});
+	}
+	/**
+	* Rewrite every usage of a source entity to read a target entity, in the background. Runs the
+	* same check as `checkReplaceSource` first and refuses with a 400 when it fails, and with a 409
+	* while another replacement is running. Admins only.
+	*/
+	async function replaceSource(params, options = {}) {
+		return transport.requestParsed(ReplacementRunStarted, "/api/ee/replacement/replace-source", {
+			...options,
+			method: "POST",
+			body: params
+		});
+	}
+	/**
+	* Create a transform from a model's query, run it, and rewrite every usage of the model to read
+	* the transform's output table, in the background; the model becomes a saved question. A failed
+	* transform run leaves the model as it was; a failed rewrite keeps the transform and its table
+	* as well, since other queries may already read them. Refuses with a 409 while another
+	* replacement is running. Admins only.
+	*/
+	async function replaceModelWithTransform(params, options = {}) {
+		return transport.requestParsed(ReplacementRunStarted, "/api/ee/replacement/replace-model-with-transform", {
+			...options,
+			method: "POST",
+			body: params
+		});
+	}
+	/**
+	* List replacement runs, newest first. `is-active: true` keeps only the run in progress,
+	* `false` only the ended ones. Admins only.
+	*/
+	async function listRuns(params = {}, options = {}) {
+		return {
+			data: await transport.requestParsed(ReplacementApiRunList, "/api/ee/replacement/runs", {
+				...options,
+				query: { "is-active": params["is-active"] }
+			}),
+			total: null
+		};
+	}
+	/** Get one replacement run by id, with its status and progress. Admins only. */
+	async function getRun(id, options = {}) {
+		return transport.requestParsed(ReplacementRun, `/api/ee/replacement/runs/${id}`, { ...options });
+	}
+	/** Cancel the replacement in progress. Refuses with a 409 once the run has ended. Admins only. */
+	async function cancelRun(id, options = {}) {
+		await transport.requestParsed(CancelRunResponse, `/api/ee/replacement/runs/${id}/cancel`, {
+			...options,
+			method: "POST"
+		});
+	}
+	return {
+		checkReplaceSource: explain("checkReplaceSource", checkReplaceSource),
+		replaceSource: explain("replaceSource", replaceSource),
+		replaceModelWithTransform: explain("replaceModelWithTransform", replaceModelWithTransform),
+		listRuns: explain("listRuns", listRuns),
+		getRun: explain("getRun", getRun),
+		cancelRun: explain("cancelRun", cancelRun)
+	};
+}
+//#endregion
+export { replacementResource };

package/dist/resources/request-body.d.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+//#region src/resources/request-body.d.ts
+/**
+ * Parse the body a caller hands a method, refusing one that does not match `schema` before any
+ * request. `what` names the body in the refusal.
+ */
+declare function parseRequestBody<T>(schema: z.ZodType<T>, value: unknown, what: string): T;
+//#endregion
+export { parseRequestBody };

package/dist/resources/request-body.js

@@ -0,0 +1,13 @@
+import { ConfigError, formatZodIssue } from "../errors.js";
+//#region src/resources/request-body.ts
+/**
+* Parse the body a caller hands a method, refusing one that does not match `schema` before any
+* request. `what` names the body in the refusal.
+*/
+function parseRequestBody(schema, value, what) {
+	const parsed = schema.safeParse(value);
+	if (!parsed.success) throw new ConfigError(`invalid ${what}: ${parsed.error.issues.map(formatZodIssue).join("; ")}`);
+	return parsed.data;
+}
+//#endregion
+export { parseRequestBody };

package/dist/resources/revision.d.ts

@@ -0,0 +1,70 @@
+import { f as RequestOptions, h as Transport } from "../transport-E0ZaPNWJ.js";
+import { t as ListResult } from "../list-BT_bBm9Z.js";
+//#region src/resources/revision.d.ts
+declare function revisionResource(transport: Transport): {
+  list: (entity: "card" | "dashboard" | "document" | "measure" | "segment" | "transform" | "transform-test", id: number, options?: RequestOptions | undefined) => Promise<ListResult<{
+    [x: string]: unknown;
+    id: number;
+    timestamp: string;
+    is_creation: boolean;
+    is_reversion: boolean;
+    most_recent: boolean;
+    diff: {
+      [x: string]: unknown;
+    } | null;
+    description: string;
+    has_multiple_changes: boolean;
+    user: {
+      [x: string]: unknown;
+      id: number;
+      first_name: string | null;
+      last_name: string | null;
+      common_name: string;
+    };
+  }>>;
+  revert: (params: {
+    entity: "card" | "dashboard" | "document" | "measure" | "segment" | "transform" | "transform-test";
+    id: number;
+    revision_id: number;
+  }, options?: RequestOptions | undefined) => Promise<{
+    outcome: "reverted";
+    revision: {
+      [x: string]: unknown;
+      id: number;
+      timestamp: string;
+      is_creation: boolean;
+      is_reversion: boolean;
+      most_recent: boolean;
+      diff: {
+        [x: string]: unknown;
+      } | null;
+      description: string;
+      has_multiple_changes: boolean;
+      user: {
+        [x: string]: unknown;
+        id: number;
+        first_name: string | null;
+        last_name: string | null;
+        common_name: string;
+      };
+    };
+  } | {
+    outcome: "unchanged";
+    revision: {
+      [x: string]: unknown;
+      id: number;
+      model: string;
+      model_id: number;
+      user_id: number;
+      object: {
+        [x: string]: unknown;
+      };
+      timestamp: string;
+      is_creation: boolean;
+      is_reversion: boolean;
+      most_recent: boolean;
+    };
+  }>;
+};
+//#endregion
+export { revisionResource };

package/dist/resources/revision.js

@@ -0,0 +1,51 @@
+import { t as explainer } from "../refusal-B9aeHMc9.js";
+import { Revision, RevisionRow } from "../domain/revision.js";
+import { z } from "zod";
+//#region src/resources/revision.ts
+const RevisionApiList = z.array(Revision);
+const RevisionApiRevert = z.union([Revision.transform((revision) => ({
+	outcome: "reverted",
+	revision
+})), RevisionRow.transform((revision) => ({
+	outcome: "unchanged",
+	revision
+}))]);
+const ENTITY_FEATURES = {
+	measure: "measures",
+	transform: "transforms",
+	"transform-test": "transformTests"
+};
+function entityFeatures(entity) {
+	const feature = ENTITY_FEATURES[entity];
+	return feature === void 0 ? [] : [{
+		feature,
+		fields: ["entity"]
+	}];
+}
+function revisionResource(transport) {
+	const { explain } = explainer(transport, "revision");
+	/** List the revisions of an entity the caller may read, newest first, each with its diff. */
+	async function list(entity, id, options = {}) {
+		return {
+			data: await transport.requestParsed(RevisionApiList, `/api/revision/${entity}/${id}`, { ...options }),
+			total: null
+		};
+	}
+	/**
+	* Revert an entity to one of its prior revisions. Needs write access to the entity, and for a
+	* card the permission to run the query being restored.
+	*/
+	async function revert(params, options = {}) {
+		return transport.requestParsed(RevisionApiRevert, "/api/revision/revert", {
+			...options,
+			method: "POST",
+			body: params
+		});
+	}
+	return {
+		list: explain("list", list, entityFeatures),
+		revert: explain("revert", revert, (params) => entityFeatures(params.entity))
+	};
+}
+//#endregion
+export { revisionResource };

package/dist/resources/search.d.ts

@@ -0,0 +1,2 @@
+import { n as SearchParams, r as searchResource, t as SearchPage } from "../search-BxJipLN6.js";
+export { SearchPage, SearchParams, searchResource };

package/dist/resources/search.js

@@ -0,0 +1,57 @@
+import { t as explainer } from "../refusal-B9aeHMc9.js";
+import { SearchResult } from "../domain/search.js";
+import { z } from "zod";
+//#region src/resources/search.ts
+const SearchApiResponse = z.object({
+	data: z.array(SearchResult),
+	total: z.number().int().nonnegative()
+}).loose();
+function verifiedFeatures(params = {}) {
+	return params.verified === true ? [{
+		feature: "contentVerification",
+		fields: ["verified"]
+	}] : [];
+}
+function searchResource(transport) {
+	const { explain } = explainer(transport, "search");
+	/**
+	* Search over the instance's content, ranked against `q`. `models` narrows which kinds of entity
+	* may match, `archived` swaps the active set for the archived one, `table_db_id` restricts to
+	* items on one database, `verified` to verified content, `collection` to one collection and its
+	* descendants, `created_by` to items created by any of those users, `search_native_query` also
+	* matches native query text but narrows to the models that carry one (cards, models, metrics,
+	* actions, transforms), `include_metadata` attaches each card's `result_metadata`,
+	* `include_dashboard_questions` also matches questions saved into a dashboard (excluded by
+	* default), and `limit`/`offset` are the window the server applies before ranking hydration.
+	* `verified` needs the `content_verification` premium feature, and is refused before the wire
+	* without it: a server granting neither it nor `official_collections` refuses the filter, and one
+	* granting `official_collections` alone takes it without applying it.
+	*/
+	async function query(params = {}, options = {}) {
+		await transport.requireFeatures(verifiedFeatures(params).map((requirement) => requirement.feature), options);
+		const response = await transport.requestParsed(SearchApiResponse, "/api/search", {
+			...options,
+			query: {
+				q: params.q,
+				models: params.models,
+				archived: params.archived,
+				limit: params.limit,
+				offset: params.offset,
+				table_db_id: params.table_db_id,
+				verified: params.verified,
+				collection: params.collection,
+				created_by: params.created_by,
+				search_native_query: params.search_native_query,
+				include_metadata: params.include_metadata,
+				include_dashboard_questions: params.include_dashboard_questions
+			}
+		});
+		return {
+			data: response.data,
+			total: response.total
+		};
+	}
+	return { query: explain("query", query, verifiedFeatures) };
+}
+//#endregion
+export { searchResource };