@quanthea/plugin-kit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Josep Boix Requesens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# @quanthea/plugin-kit
+
+The kit a [quanthea](https://github.com/jboix/quanthea) connector plugin is written against. A
+plugin adds connector kinds, such as a new database, to a quanthea server.
+
+The kit is in beta: version 0.x, kit version 0.
+
+## Install
+
+```sh
+bun add -d @quanthea/plugin-kit@^0.1.0
+```
+
+It is a development dependency. A plugin imports only types from it, and quanthea passes the live
+kit to the plugin when it loads it, so the bundle carries none of the kit's code.
+
+## Write a plugin
+
+The plugin is one bundled ES module. It exports the kit version it is built for and, as default, a
+function that receives the kit and returns its kinds:
+
+```ts
+import type { ConnectorKit } from '@quanthea/plugin-kit';
+
+export const kitVersion = 0;
+
+export default function plugin(kit: ConnectorKit) {
+  return [kit.defineConnector({ kind: 'example', configSchema: kit.z.object({ … }), … })];
+}
+```
+
+- Build the schemas with `kit.z` and throw `kit.ConnectorError`: they are quanthea's own.
+- Name the package `quanthea-plugin-<name>` or `@scope/quanthea-plugin-<name>`, with the
+  `quanthea-plugin` keyword.
+- Add the manifest field to `package.json`: `"quanthea": { "kitVersion": 0, "main": "dist/plugin.js" }`.
+
+[Publishing a plugin](https://github.com/jboix/quanthea/blob/main/docs/connectors.md#publishing-a-plugin)
+covers the bundle, the manifest and publishing. The
+[SQLite example](https://github.com/jboix/quanthea/tree/main/examples/quanthea-plugin-sqlite) is a
+complete plugin to start from.
+
+## Test a plugin
+
+`@quanthea/plugin-kit/testing` runs under `bun test`:
+
+- `createTestKit()` returns the live kit, the same one quanthea passes at load.
+- `testConnectorConformance(kind, fixture)` registers the tests every kind passes: the static
+  checks quanthea runs at install and load, then queries against a real source.
+
+## Versions
+
+The kit's major version equals `kitVersion`. While the kit is in 0.x:
+
+- A **minor** version, such as 0.2.0, adds to the kit.
+- A **patch** version, such as 0.1.1, fixes it.
+
+npm's caret stays within one minor version on 0.x: `^0.1.0` takes the 0.1.x fixes, and moving to
+0.2.0 is your choice. At 1.0, the kit becomes 1.0.0 and `kitVersion` becomes 1, and quanthea stops
+loading plugins built for kit version 0.
+
+## Licence
+
+MIT

package/checks.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The static checks of a connector kind: what it declares, without a source. The loader runs them
+ * on every plugin's kinds at startup, the installer before it keeps a plugin, and the conformance
+ * suite in every kind's tests, so a kind that passes its own tests passes the loader. A plugin may
+ * return an object it did not build with `defineConnector`, so nothing is taken for granted.
+ */
+/**
+ * Everything wrong with what a kind declares.
+ *
+ * @param kind - The kind, as a plugin returned it.
+ * @returns The problems, empty when it passes.
+ */
+export declare function kindProblems(kind: unknown): string[];

package/chunk-3ayrhcmg.js

@@ -0,0 +1,5 @@
+// @bun
+// packages/plugin-kit/src/kit.ts
+var kitVersion2 = 0;
+
+export { kitVersion2 };

package/connector-kind.d.ts

@@ -0,0 +1,128 @@
+/** The contract of a connector kind: what it declares, and what an open connection can do. */
+import type { z } from 'zod';
+import type { Frame } from './frames.js';
+import { type BoundQuery, type ExecutionContext, type QueryLanguage, type SqlDialect, type SqlPlaceholderStyle, type SqlRowLimit } from './queries.js';
+import type { FieldReference, HealthReport, SampleResult, SchemaSnapshot } from './schema.js';
+/**
+ * An open connection to one source. The core calls it only with bound queries and guardrails it has
+ * already checked, and passes every result through its own checks.
+ */
+export interface ConnectorInstance {
+    /**
+     * Checks that the source answers and the credentials work.
+     *
+     * @param signal - Aborted when the caller gives up.
+     * @returns The health report. A failed check is a report with `ok: false`, not an error.
+     */
+    test(signal: AbortSignal): Promise<HealthReport>;
+    /**
+     * Reads the shape of the source: entities and fields, never values.
+     *
+     * @param signal - Aborted when the caller gives up.
+     * @returns The schema snapshot.
+     * @throws {ConnectorError} When the source cannot be read.
+     */
+    describe(signal: AbortSignal): Promise<SchemaSnapshot>;
+    /**
+     * Reads distinct values of one field.
+     *
+     * @param field - The field, as named in the schema snapshot.
+     * @param limit - How many values to return at most.
+     * @param signal - Aborted when the caller gives up.
+     * @returns The values, and whether there are more.
+     * @throws {ConnectorError} When the field does not exist or the source fails.
+     */
+    sampleValues(field: FieldReference, limit: number, signal: AbortSignal): Promise<SampleResult>;
+    /**
+     * Runs a bound query.
+     *
+     * @param query - The query, in the connector kind's language.
+     * @param context - The time range, row limit and abort signal to respect.
+     * @returns One or more frames named `context.refId`.
+     * @throws {ConnectorError} When the query fails, times out or is aborted.
+     */
+    execute(query: BoundQuery, context: ExecutionContext): Promise<Frame[]>;
+    /**
+     * Releases pooled connections. The core calls it when the connector is changed or deleted.
+     *
+     * @returns When everything is released.
+     */
+    close(): Promise<void>;
+}
+/**
+ * A kind's logo, so people tell kinds apart at a glance: one SVG path on a 24×24 grid, filled with
+ * one colour. It is data, not markup: the app draws it.
+ */
+export interface ConnectorIcon {
+    /** The path data, the `d` attribute of an SVG `path`. */
+    readonly path: string;
+    /** The fill colour, as `#rrggbb`. */
+    readonly color: string;
+}
+/** What {@link ConnectorKind.open} receives: the parsed configuration and credentials. */
+export interface OpenOptions<Config, Secret> {
+    /** The configuration, parsed with the kind's config schema. */
+    readonly config: Config;
+    /** The credentials, parsed with the kind's secret schema. */
+    readonly secret: Secret;
+}
+/**
+ * A kind of data source, such as PostgreSQL. It declares its settings as Zod schemas, from which the
+ * app builds its forms, and opens connections.
+ */
+export interface ConnectorKind<ConfigSchema extends z.ZodType = z.ZodType, SecretSchema extends z.ZodType = z.ZodType> {
+    /** A stable identifier, lowercase with dashes, such as `postgres`. Stored with each connector. */
+    readonly kind: string;
+    /** The name shown to people, such as `PostgreSQL`. */
+    readonly displayName: string;
+    /** The kind's logo. Without one, the app shows the first letters of its name. */
+    readonly icon?: ConnectorIcon;
+    /** Other names the add form finds the kind by, such as `timescaledb` for PostgreSQL. */
+    readonly aliases?: readonly string[];
+    /** The language of this kind's query templates. The core binds variables for it. */
+    readonly language: QueryLanguage;
+    /** The SQL dialect, which a `sql` kind must declare: how the core binds its templates. */
+    readonly dialect?: SqlDialect;
+    /** For the `ansi` dialect: how the source writes a placeholder. `?` when not given. */
+    readonly placeholders?: SqlPlaceholderStyle;
+    /** For the `ansi` dialect: how the source limits rows. `fetch` when not given. */
+    readonly rowLimit?: SqlRowLimit;
+    /**
+     * Everything but the credentials: host, database, TLS options. Stored in plain text and shown to
+     * admins. Give each field a title and a description with `.meta()`; the form is built from them.
+     */
+    readonly configSchema: ConfigSchema;
+    /** The credentials. Stored encrypted and never returned by the API. */
+    readonly secretSchema: SecretSchema;
+    /**
+     * How to get each shape of data in this kind's language, for the agent: about data, never about
+     * charts. Adding a connector kind means adding its guide, with no chart recipe changing.
+     */
+    readonly queryGuide?: string;
+    /**
+     * Says where a connector points, shown under its name, such as
+     * `postgres://dash_ro@orders-replica:5432/orders`. It must not include credentials.
+     *
+     * @param config - The parsed configuration.
+     * @returns One line.
+     */
+    describeTarget?(config: z.output<ConfigSchema>): string;
+    /**
+     * Opens a connection. It must not contact the source; the first call does.
+     *
+     * @param options - The parsed configuration and credentials.
+     * @returns The connection.
+     */
+    open(options: OpenOptions<z.output<ConfigSchema>, z.output<SecretSchema>>): ConnectorInstance;
+}
+/** A connector kind whatever its schemas, as the registry holds them. */
+export type AnyConnectorKind = ConnectorKind<z.ZodType, z.ZodType>;
+/**
+ * Declares a connector kind. It checks the identifier and keeps the schema types for `open`.
+ *
+ * @param definition - The kind.
+ * @returns The same kind.
+ * @throws {Error} When the identifier is not lowercase letters, digits and dashes, a SQL kind
+ *   declares no dialect, or the icon is malformed.
+ */
+export declare function defineConnector<ConfigSchema extends z.ZodType, SecretSchema extends z.ZodType>(definition: ConnectorKind<ConfigSchema, SecretSchema>): ConnectorKind<ConfigSchema, SecretSchema>;

package/errors.d.ts

@@ -0,0 +1,34 @@
+/** The one error type connectors throw. */
+/** Why a connector call can fail. */
+declare const connectorErrorCodes: readonly ["unreachable", "authentication", "permission", "syntax", "not_found", "timeout", "rejected", "internal"];
+/** Why a connector call failed. The gate and the UI switch on this. */
+export type ConnectorErrorCode = (typeof connectorErrorCodes)[number];
+/**
+ * A failed connector call. `message` is the source's own text and may quote data, such as a value in
+ * a type error; only people allowed to see the data get it. `safeMessage` must quote no data: the
+ * model receives it whatever the connector's access level.
+ */
+export declare class ConnectorError extends Error {
+    /** Why the call failed. */
+    readonly code: ConnectorErrorCode;
+    /** A description that quotes no values from the source. Identifiers are fine. */
+    readonly safeMessage: string;
+    /**
+     * Creates the error.
+     *
+     * @param code - Why the call failed.
+     * @param safeMessage - A description that quotes no values from the source.
+     * @param message - The source's own message, which may quote values. Defaults to `safeMessage`.
+     * @param options - The underlying error, as `cause`.
+     */
+    constructor(code: ConnectorErrorCode, safeMessage: string, message?: string, options?: ErrorOptions);
+    /**
+     * Whether a value is a connector error: an instance of this class, or of another copy of it, by
+     * the brand, with a known code and a safe message. So `instanceof` holds across copies.
+     *
+     * @param value - The value.
+     * @returns `true` for a connector error.
+     */
+    static [Symbol.hasInstance](value: unknown): boolean;
+}
+export {};

package/frame-builder.d.ts

@@ -0,0 +1,38 @@
+/** Builds a frame row by row, stopping at the row limit. */
+import type { Field, Frame } from './frames.js';
+/** Collects rows into a frame. */
+export interface FrameBuilder {
+    /**
+     * Adds a row. Past the row limit the row is dropped and the frame is marked truncated.
+     *
+     * @param row - One value per field, in field order.
+     * @returns `false` when the row was dropped because the frame is full: stop reading.
+     */
+    add(row: readonly unknown[]): boolean;
+    /**
+     * Finishes the frame.
+     *
+     * @param durationMs - How long the query took.
+     * @returns The frame.
+     */
+    build(durationMs: number): Frame;
+}
+/** What a frame builder needs to know. */
+export interface FrameBuilderOptions {
+    /** The frame name the query was given (`ExecutionContext.refId`). */
+    readonly refId: string;
+    /** The fields, in column order. */
+    readonly fields: readonly Field[];
+    /** The row limit (`ExecutionContext.maxRows`). */
+    readonly maxRows: number;
+    /** A name for the frame, such as a series name. */
+    readonly name?: string;
+}
+/**
+ * Creates a frame builder. Read one row more than the limit so the builder can tell the frame was
+ * truncated.
+ *
+ * @param options - The frame name, fields and row limit.
+ * @returns The builder.
+ */
+export declare function createFrameBuilder(options: FrameBuilderOptions): FrameBuilder;

package/frames.d.ts

@@ -0,0 +1,62 @@
+/** Result frames: the column-based format every connector returns and the browser renders. */
+import { z } from 'zod';
+/** The value types a field can hold. Times are Unix epoch milliseconds. */
+export declare const fieldTypes: readonly ["time", "number", "string", "boolean"];
+/** A field value type. */
+export type FieldType = (typeof fieldTypes)[number];
+/** Validates a field: one column of a frame. */
+export declare const fieldSchema: z.ZodObject<{
+    name: z.ZodString;
+    type: z.ZodEnum<{
+        string: "string";
+        number: "number";
+        boolean: "boolean";
+        time: "time";
+    }>;
+    labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    unit: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/** One column of a frame: its name, value type, and for time series, the series labels. */
+export type Field = z.infer<typeof fieldSchema>;
+/** Validates the shape of a frame. {@link frameProblems} also checks the values. */
+export declare const frameSchema: z.ZodObject<{
+    refId: z.ZodString;
+    name: z.ZodOptional<z.ZodString>;
+    fields: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodEnum<{
+            string: "string";
+            number: "number";
+            boolean: "boolean";
+            time: "time";
+        }>;
+        labels: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        unit: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    values: z.ZodArray<z.ZodArray<z.ZodUnknown>>;
+    meta: z.ZodObject<{
+        rowCount: z.ZodNumber;
+        truncated: z.ZodBoolean;
+        durationMs: z.ZodNumber;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * A query result in columns: `values[i]` holds the values of `fields[i]`, one per row. A missing
+ * value is `null`.
+ */
+export type Frame = z.infer<typeof frameSchema>;
+/**
+ * Lists everything wrong with a frame: its shape, column lengths, and value types.
+ *
+ * @param frame - The frame to check, as received.
+ * @returns One sentence per problem, empty when the frame is valid.
+ */
+export declare function frameProblems(frame: unknown): string[];
+/**
+ * Orders two values of a frame: numbers by value, anything else as text.
+ *
+ * @param first - One value.
+ * @param second - The other.
+ * @returns Negative, zero or positive.
+ */
+export declare function compareFrameValues(first: unknown, second: unknown): number;

package/host.d.ts

@@ -0,0 +1,12 @@
+import { type ConnectorKit } from './kit.js';
+/** The kit every plugin receives. */
+export declare const hostKit: ConnectorKit;
+export { kindProblems } from './checks.js';
+export { type AnyConnectorKind, type ConnectorIcon, type ConnectorInstance, type ConnectorKind, defineConnector, } from './connector-kind.js';
+export { ConnectorError, type ConnectorErrorCode } from './errors.js';
+export { createFrameBuilder } from './frame-builder.js';
+export { createHttpClient, type HttpClient, type HttpResponse } from './http.js';
+export { kitVersion } from './kit.js';
+export { type BoundQuery, type ExecutionContext, type HttpField, type HttpQuery, type LogqlQuery, type MongodbQuery, type PromqlQuery, type QueryLanguage, type RedisQuery, type SearchQuery, type SqlDialect, type SqlParameter, type SqlPlaceholderStyle, type SqlQuery, type SqlRowLimit, sqlDialects, type TimeRange, } from './queries.js';
+export type { FieldReference, HealthReport, SampleResult, SchemaEntity, SchemaField, SchemaSnapshot, } from './schema.js';
+export { type SeriesData, seriesFrames } from './series-frames.js';

package/http-address.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Whether an address is a cloud metadata address.
+ *
+ * @param address - An IP address, or a URL host with IPv6 in brackets.
+ * @returns `true` for a metadata address, `false` for any other address or a name.
+ */
+export declare function isMetadataAddress(address: string): boolean;
+/**
+ * Checks that a URL does not point to a cloud metadata address, by its host and, for a name, by
+ * the addresses it resolves to. A name that does not resolve passes: the request then fails as
+ * unreachable.
+ *
+ * @param url - The URL about to be called.
+ * @param sourceName - The source, for the message, such as `ClickHouse`.
+ * @returns Once the address is checked.
+ * @throws {ConnectorError} `rejected` when the host is or resolves to a metadata address.
+ */
+export declare function checkDestination(url: URL, sourceName: string): Promise<void>;

package/http.d.ts

@@ -0,0 +1,91 @@
+/** How a client reaches its source. */
+export interface HttpClientOptions {
+    /** The base URL. Its origin is the only one called; its path prefixes every request path. */
+    readonly baseUrl: string;
+    /** The source, in error messages, such as `ClickHouse`. */
+    readonly sourceName: string;
+    /** Headers sent with every request, such as `Authorization`. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Whether to check the server certificate. Defaults to `true`. */
+    readonly verifyTls?: boolean;
+    /** The longest a request may take, body included, in milliseconds. Defaults to 120 seconds. */
+    readonly timeoutMs?: number;
+    /** The most bytes of a body read. Defaults to 64 MiB. */
+    readonly maxBytes?: number;
+}
+/** The methods a connector sends. */
+type HttpMethod = 'GET' | 'POST' | 'DELETE';
+/** One request. */
+export interface HttpRequest {
+    /** The method. Defaults to `GET`. */
+    readonly method?: HttpMethod;
+    /**
+     * The path under the base URL, starting with `/`, or an absolute URL on the same origin, such as
+     * a link to the next page the source returned.
+     */
+    readonly path: string;
+    /** Query string parameters; an array value repeats the parameter. */
+    readonly query?: Readonly<Record<string, string | readonly string[]>>;
+    /** Headers for this request, added to the client's. */
+    readonly headers?: Readonly<Record<string, string>>;
+    /** The body of a POST. */
+    readonly body?: string;
+    /** Aborts the request and the reading of its body. */
+    readonly signal: AbortSignal;
+}
+/** A response whose body is read at most once, within the byte cap. */
+export interface HttpResponse {
+    /** The HTTP status. */
+    readonly status: number;
+    /** Whether the status is 2xx. */
+    readonly ok: boolean;
+    /** The response headers. */
+    readonly headers: Headers;
+    /**
+     * Reads the body as text.
+     *
+     * @returns The text.
+     * @throws {ConnectorError} Past the byte cap, at the timeout or when the connection fails.
+     */
+    text(): Promise<string>;
+    /**
+     * Reads the body as JSON.
+     *
+     * @returns The parsed value.
+     * @throws {ConnectorError} When the body is not JSON, and as {@link HttpResponse.text}.
+     */
+    json(): Promise<unknown>;
+    /**
+     * Reads the body line by line, without the line ends. Stopping early closes the connection.
+     *
+     * @returns The lines.
+     * @throws {ConnectorError} As {@link HttpResponse.text}.
+     */
+    lines(): AsyncGenerator<string>;
+    /**
+     * Leaves the body unread and closes the connection.
+     *
+     * @returns Once the body is cancelled.
+     */
+    cancel(): Promise<void>;
+}
+/** Sends requests to one source. */
+export interface HttpClient {
+    /**
+     * Sends a request.
+     *
+     * @param request - The request.
+     * @returns The response, whatever its status.
+     * @throws {ConnectorError} `unreachable` when the connection fails, `timeout` when the signal or
+     *   the timeout fires, `rejected` for a redirect to another origin or a metadata address.
+     */
+    request(request: HttpRequest): Promise<HttpResponse>;
+}
+/**
+ * Creates a client for one source.
+ *
+ * @param options - The base URL, headers, TLS setting and limits.
+ * @returns The client.
+ */
+export declare function createHttpClient(options: HttpClientOptions): HttpClient;
+export {};

package/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The public kit: the types a connector plugin is written against, and the kit version. A plugin
+ * imports types only from here; at load, quanthea passes it the live kit (`ConnectorKit`).
+ *
+ * ```ts
+ * import type { ConnectorKit } from '@quanthea/plugin-kit';
+ * export const kitVersion = 0;
+ * export default function plugin(kit: ConnectorKit) {
+ *   return [kit.defineConnector({ kind: 'example', … })];
+ * }
+ * ```
+ */
+export type { ConnectorIcon, ConnectorInstance, ConnectorKind, OpenOptions, } from './connector-kind.js';
+export type { ConnectorError, ConnectorErrorCode } from './errors.js';
+export type { FrameBuilder, FrameBuilderOptions } from './frame-builder.js';
+export type { Field, FieldType, Frame } from './frames.js';
+export type { HttpClient, HttpClientOptions, HttpRequest, HttpResponse } from './http.js';
+export { type ConnectorKit, type ConnectorPlugin, kitVersion } from './kit.js';
+export type { BoundQuery, ExecutionContext, HttpField, HttpQuery, LogqlQuery, MongodbQuery, PromqlQuery, QueryLanguage, RedisQuery, SearchQuery, SqlDialect, SqlParameter, SqlPlaceholderStyle, SqlQuery, SqlRowLimit, TimeRange, } from './queries.js';
+export type { FieldReference, HealthReport, SampleResult, SchemaEntity, SchemaField, SchemaSnapshot, } from './schema.js';
+export type { SeriesData } from './series-frames.js';

package/index.js

@@ -0,0 +1,7 @@
+// @bun
+import {
+  kitVersion2
+} from "./chunk-3ayrhcmg.js";
+export {
+  kitVersion2 as kitVersion
+};

package/kit.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The kit quanthea hands a plugin when it loads it, and the shape of a plugin. The kit is the live
+ * one: its Zod, its error class and its helpers are the server's own, so a plugin's schemas and
+ * errors are the ones the core checks.
+ */
+import type { z } from 'zod';
+import type { ConnectorKind, defineConnector } from './connector-kind.js';
+import type { ConnectorError } from './errors.js';
+import type { createFrameBuilder } from './frame-builder.js';
+import type { createHttpClient } from './http.js';
+import type { seriesFrames } from './series-frames.js';
+/** The version of the kit this package describes. A plugin exports the version it was built for. */
+export declare const kitVersion = 0;
+/** What a plugin receives. */
+export interface ConnectorKit {
+    /** The kit version, {@link kitVersion}. */
+    readonly version: typeof kitVersion;
+    /** The server's Zod: build the configuration and credential schemas with it. */
+    readonly z: typeof z;
+    /** Declares a connector kind, with the same checks as the built-in kinds. */
+    readonly defineConnector: typeof defineConnector;
+    /** The error a connector throws, with a code and a message safe to show. */
+    readonly ConnectorError: typeof ConnectorError;
+    /** Builds a frame row by row, with the row limit and truncation. */
+    readonly createFrameBuilder: typeof createFrameBuilder;
+    /** An HTTP client held to one origin, with a timeout and a size cap. */
+    readonly createHttpClient: typeof createHttpClient;
+    /** Turns results in the Prometheus API format into frames. */
+    readonly seriesFrames: typeof seriesFrames;
+}
+/**
+ * A plugin's default export: given the kit, the connector kinds it adds.
+ *
+ * @param kit - The kit.
+ * @returns The kinds.
+ */
+export type ConnectorPlugin = (kit: ConnectorKit) => readonly ConnectorKind[];

package/languages.d.ts

@@ -0,0 +1,16 @@
+/** The query languages a connector kind can speak. The core binds each one; a plugin picks one. */
+import { z } from 'zod';
+/** The query languages connectors speak. */
+export declare const queryLanguages: readonly ["sql", "promql", "search", "logql", "http", "redis", "mongodb"];
+/** Validates a query language. */
+export declare const queryLanguageSchema: z.ZodEnum<{
+    sql: "sql";
+    promql: "promql";
+    search: "search";
+    logql: "logql";
+    http: "http";
+    redis: "redis";
+    mongodb: "mongodb";
+}>;
+/** A query language. */
+export type QueryLanguage = z.infer<typeof queryLanguageSchema>;

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@quanthea/plugin-kit",
+  "version": "0.1.0",
+  "description": "The connector kit: the types a quanthea connector plugin is written against, a test kit and the conformance suite.",
+  "keywords": [
+    "quanthea",
+    "connector",
+    "plugin",
+    "kit"
+  ],
+  "license": "MIT",
+  "author": "Josep Boix Requesens",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jboix/quanthea.git",
+    "directory": "packages/plugin-kit"
+  },
+  "homepage": "https://github.com/jboix/quanthea/tree/main/packages/plugin-kit#readme",
+  "bugs": {
+    "url": "https://github.com/jboix/quanthea/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./testing": {
+      "types": "./testing.d.ts",
+      "default": "./testing.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "zod": "^4.6.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}