@incorta/sdk 1.8.0

package/dist/index.d.cts

@@ -0,0 +1,842 @@
+import { IncortaAuthConfig, IncortaAuth, IncortaUser, AuthSession } from '@incorta/auth';
+export { AuthSession, IncortaAuth, IncortaUser } from '@incorta/auth';
+
+/**
+ * Options for {@link createIncortaClient} — every `@incorta/auth` option, plus:
+ *
+ * - `auth`: an already-built {@link IncortaAuth} to reuse instead of creating
+ *   one. When given, the auth options are ignored (they live on that instance).
+ * - `timeoutMs` / `maxRetries`: transport settings for the metadata calls.
+ */
+type IncortaClientConfig = IncortaAuthConfig & {
+    /**
+     * An existing `@incorta/auth` instance to borrow sessions from. Prefer this
+     * whenever the app already mounts one — a second instance would mean two
+     * sets of OAuth state for the same users.
+     */
+    auth?: IncortaAuth;
+    /**
+     * Per-request timeout in milliseconds.
+     * @default 30000
+     */
+    timeoutMs?: number;
+    /**
+     * Retries for transient failures (HTTP 429 and 5xx, and network errors).
+     * Client errors are never retried — replaying them cannot help.
+     * @default 3
+     */
+    maxRetries?: number;
+};
+
+/**
+ * Internal HTTP transport.
+ *
+ * Owns the auth header, the retry policy, and the translation of error
+ * responses into the error hierarchy. Not part of the public API.
+ *
+ * The bearer token is resolved per request rather than captured once: it
+ * belongs to a user session that `@incorta/auth` refreshes underneath us, so
+ * reading it late is what keeps a long-lived scoped client honest.
+ */
+
+/**
+ * Supplies the access token for one request. Throws
+ * {@link IncortaSessionExpiredError} when the session it draws on has aged out.
+ */
+type TokenProvider = () => string | Promise<string>;
+
+/**
+ * Values the Incorta API accepts and returns.
+ *
+ * Each is a string-literal union (compile-time safety) paired with a frozen
+ * array of its members (runtime validation, for JavaScript callers who get no
+ * type checking).
+ */
+/**
+ * Filter for `client.schemas.list()`.
+ *
+ * Passing an unrecognised value to the API is *silently* treated as `BUSINESS`
+ * and returns HTTP 200, so a typo yields plausible-looking but wrong results.
+ * The client validates locally before sending the request to make that failure
+ * loud.
+ */
+declare const SCHEMA_TYPES: readonly ["ALL", "PHYSICAL", "BUSINESS"];
+type SchemaType = (typeof SCHEMA_TYPES)[number];
+/** Ordering accepted by the schema list endpoint. */
+declare const SORT_ORDERS: readonly ["NAME_ASC", "NAME_DESC"];
+type SortBy = (typeof SORT_ORDERS)[number];
+/**
+ * Normalised type of a schema object.
+ *
+ * The API reports business views as `"BUSSINESS_VIEW"` (three S's). That
+ * spelling is preserved as the value for round-tripping, but {@link parseObjectType}
+ * accepts the corrected spelling too, so callers keep working if Incorta ever
+ * fixes it.
+ */
+type ObjectType = "table" | "BUSSINESS_VIEW" | "UNKNOWN";
+/**
+ * Converts an API type string into an {@link ObjectType}.
+ *
+ * Unrecognised values map to `"UNKNOWN"` rather than throwing: an unfamiliar
+ * object type should not break metadata listing.
+ */
+declare function parseObjectType(raw: string | null | undefined): ObjectType;
+/**
+ * Result format for a data query.
+ *
+ * `csv` comes back as one text blob rather than parsed rows, and cannot be
+ * combined with an unstringified response: asking for both returns only the
+ * header line, with HTTP 200. The client blocks that combination.
+ */
+declare const QUERY_FORMATS: readonly ["json", "csv"];
+type QueryFormat = (typeof QUERY_FORMATS)[number];
+/** Comparison operator for a filter. */
+declare const FILTER_OPS: readonly ["=", "!=", ">", ">=", "<", "<=", "BETWEEN", "IN_LIST"];
+type FilterOp = (typeof FILTER_OPS)[number];
+/** Aggregation function applied to a measure. */
+declare const AGGREGATIONS: readonly ["sum", "count", "distinct", "median", "average", "min", "max"];
+type Aggregation = (typeof AGGREGATIONS)[number];
+/**
+ * How null cells are rendered in a result.
+ *
+ * Incorta's published API schema also lists `DASH`, but the server rejects it
+ * with HTTP 400 — it is deliberately absent here rather than offered and broken.
+ */
+declare const NULL_VALUE_AS: readonly ["NULL", "EMPTY"];
+type NullValueAs = (typeof NULL_VALUE_AS)[number];
+/** Direction of a sort criterion. */
+declare const SORT_DIRECTIONS: readonly ["asc", "desc"];
+type SortDirection = (typeof SORT_DIRECTIONS)[number];
+/** Semantic role Incorta assigns to a column. */
+declare const COLUMN_FUNCTIONS: readonly ["key", "dimension", "measure", "attribute", "unknown"];
+type ColumnFunction = (typeof COLUMN_FUNCTIONS)[number];
+/** Converts an API function string into a {@link ColumnFunction}. */
+declare function parseColumnFunction(raw: string | null | undefined): ColumnFunction;
+
+/**
+ * Querying data out of business views.
+ *
+ * Where the schema resources describe *what exists*, this one reads *what is in
+ * it*. It wraps the single `POST {apiRoot}/query` endpoint, which takes an
+ * `InsightQuery` and returns a pivot: measures, optionally grouped by row and
+ * column dimensions.
+ *
+ * Fields are addressed by their fully qualified name, `SCHEMA.VIEW.COLUMN` —
+ * for example `HR_BS.Employee_BS.SALARY`.
+ *
+ * Three behaviours of that endpoint are worth knowing, because all three fail
+ * quietly rather than with an error:
+ *
+ * - Omitting `aggregate` makes Incorta aggregate anyway. A non-aggregate
+ *   extract written without it returns **zero rows with HTTP 200**, and reports
+ *   string columns as `double`. This client always sends the flag.
+ * - An aggregate query ignores the top-level `sorting` list entirely; sorting
+ *   is read only from within a dimension. This client routes each sort onto the
+ *   dimension it names, and rejects one that matches none.
+ * - `format: "csv"` combined with an unstringified response returns only the
+ *   header line, also with HTTP 200. `csv()` handles the encoding itself.
+ */
+
+/** Rows per request when `iterRows` is not given a size. */
+declare const DEFAULT_QUERY_PAGE_SIZE = 1000;
+/** One sorting criterion. */
+interface Sort {
+    /** Fully qualified column to sort on. */
+    field?: string;
+    /** Expression to sort on, instead of `field`. */
+    formula?: string;
+    /** @default "asc" */
+    dir?: SortDirection;
+    label?: string;
+    /** Sort by the nth measure rather than a dimension. */
+    measureIndex?: number;
+}
+/** A filter applied to the source rows, before any aggregation. */
+interface Filter {
+    type: "fieldKey" | "formulaKey";
+    /** Required when `type` is `"fieldKey"`. */
+    fieldKey?: string;
+    /** Required when `type` is `"formulaKey"`. */
+    formulaKey?: string;
+    op?: FilterOp;
+    values?: (string | number)[];
+    label?: string;
+    prompt?: boolean;
+    caseSensitive?: boolean;
+}
+/** A filter applied *after* aggregation — Incorta's `HAVING`. */
+interface AggregateFilter {
+    field?: string;
+    formula?: string;
+    op?: FilterOp;
+    values?: (string | number)[];
+    aggregation?: Aggregation;
+}
+/**
+ * A value to return.
+ *
+ * In an aggregate query, `aggregation` folds the column; in a non-aggregate
+ * query it is left unset and the raw values come back.
+ */
+interface Measure {
+    field?: string;
+    formula?: string;
+    label?: string;
+    aggregation?: Aggregation;
+    /** Value scale: `"k"`, `"m"`, or `"percent"`. */
+    scale?: string;
+    /** In hierarchy min/max queries, the physical column referenced. */
+    sourceField?: string;
+    filters?: Filter[];
+}
+/** A column to group by — used for both `rows` and `columns`. */
+interface Dimension {
+    field?: string;
+    formula?: string;
+    label?: string;
+    sorting?: Sort[];
+    /** Marks the field as part of a time series (year, quarter, month, day). */
+    datePart?: boolean;
+    /** Emit a subtotal row for this level. Row dimensions only. */
+    subTotal?: boolean;
+    /** Keep groups with no matching rows. Row dimensions only. */
+    showEmptyGroups?: boolean;
+}
+/** A measure given as a bare field name is shorthand for `{ field }`. */
+type MeasureInput = Measure | string;
+/** A dimension given as a bare field name is shorthand for `{ field }`. */
+type DimensionInput = Dimension | string;
+interface QueryOptions {
+    /** Dimensions to group down the page. */
+    rows?: DimensionInput[];
+    /** Dimensions to pivot across the page. */
+    columns?: DimensionInput[];
+    /**
+     * `false` for a flat extract, `true` to fold the measures with their
+     * aggregation functions. Always sent explicitly — see the module docstring.
+     * @default false
+     */
+    aggregate?: boolean;
+    /** Applied to source rows, before aggregation. */
+    filters?: Filter[];
+    /** Applied after aggregation — Incorta's `HAVING`. */
+    aggregateFilters?: AggregateFilter[];
+    /** Result ordering. */
+    sorting?: Sort[];
+    /** Maximum rows to return; `0` means the server default. @default 0 */
+    pageSize?: number;
+    /** Zero-based row to start from. @default 0 */
+    startRow?: number;
+    /** Return values with Incorta's display formatting applied. */
+    formatted?: boolean;
+    /** How null cells are rendered. */
+    nullValueAs?: NullValueAs;
+    /** Return sample data when the result exceeds the sample size. */
+    sampled?: boolean;
+    /**
+     * Incorta login name to impersonate. Base64-encoded for you; requires the
+     * caller to hold impersonation rights.
+     */
+    asUser?: string;
+    /**
+     * Merged into the `InsightQuery` untouched, for fields this interface does
+     * not name (`ensureParentSubtotal`, `skipSelf`, `sortWithinGroups`,
+     * `distinctFilter`, `auditingInfo`).
+     */
+    advanced?: Record<string, unknown>;
+}
+/** One column of a result set, in the order it appears in each row. */
+interface ResultColumn {
+    label: string;
+    dataType: string;
+    /** Which part of the pivot this column came from. */
+    kind: "row" | "column" | "measure";
+    raw: Record<string, unknown>;
+}
+/**
+ * The rows a query returned, plus the paging state that produced them.
+ *
+ * Rows come back as arrays of strings in column order — Incorta renders every
+ * cell as text, including numbers. `records()` zips them against `headers` when
+ * a mapping is easier to work with.
+ */
+interface QueryResult {
+    /** Column descriptors, ordered rows, then columns, then measures. */
+    columns: ResultColumn[];
+    /** Column labels, in cell order. */
+    headers: string[];
+    rows: string[][];
+    /** Rows matching the query in full, beyond this page. */
+    totalRows: number;
+    startRow: number;
+    endRow: number;
+    /** Whether this response covered every matching row. */
+    complete: boolean;
+    /** Whether rows remain beyond this page. */
+    hasMore: boolean;
+    isAggregated: boolean;
+    /** Whether the data exceeded the sample size and was sampled. */
+    isSampled: boolean;
+    /** The undecoded response, for fields this model does not name. */
+    raw: Record<string, unknown>;
+    /**
+     * The rows as `{ header: cell }` objects. Duplicate labels are disambiguated
+     * with a positional suffix, so no column is silently dropped.
+     */
+    records(): Record<string, string>[];
+    /** Every cell of one column, by label, matched case-insensitively. */
+    column(label: string): string[];
+}
+interface DataResource {
+    /**
+     * Runs one query and returns its rows.
+     *
+     * @throws {IncortaConfigError} The query is malformed — caught locally,
+     *   before the request is sent.
+     * @throws {PermissionDeniedError} The user may not read this data, or may not
+     *   impersonate `asUser`.
+     */
+    query(measures: MeasureInput[], options?: QueryOptions): Promise<QueryResult>;
+    /**
+     * Yields every matching row, fetching one page at a time.
+     *
+     * Preferable to a single unbounded query on a large view, where one response
+     * can be slow and memory-hungry. `startRow` is driven internally.
+     */
+    iterRows(measures: MeasureInput[], options?: Omit<QueryOptions, "startRow">): AsyncGenerator<string[], void, undefined>;
+    /**
+     * Runs a query and returns the result as CSV text.
+     *
+     * Incorta renders the CSV itself, so this returns the body verbatim rather
+     * than re-encoding `query`'s rows. Note that the endpoint applies `pageSize`
+     * to JSON results only — a CSV request returns every matching row regardless.
+     */
+    csv(measures: MeasureInput[], options?: QueryOptions): Promise<string>;
+    /**
+     * Sends a request body verbatim and returns the decoded response.
+     *
+     * The escape hatch for query features this resource does not model. The body
+     * is sent unvalidated, so the endpoint's quiet defaults apply — set
+     * `query.aggregate` explicitly.
+     */
+    raw(body: Record<string, unknown>): Promise<unknown>;
+    /**
+     * Builds the request body without sending it. Exposed for inspection,
+     * logging, and tests.
+     */
+    buildBody(measures: MeasureInput[], options?: QueryOptions & {
+        format?: QueryFormat;
+    }): Record<string, unknown>;
+}
+/**
+ * Builds a result from the endpoint's response body.
+ *
+ * Cells arrive as one flat array per row, ordered row dimensions, then column
+ * dimensions, then measures; the headers are reported in three separate lists
+ * and are stitched back into that same order here.
+ */
+declare function parseQueryResult(payload: Record<string, unknown>): QueryResult;
+
+/**
+ * Typed models for Incorta metadata.
+ *
+ * The API returns structurally different payloads for physical and business
+ * schemas, and the two are modelled separately rather than merged:
+ *
+ * - A **physical** schema responds with `tablesDetails` only; the
+ *   `viewsDetails` key is absent entirely.
+ * - A **business** schema responds with `viewsDetails` only.
+ *
+ * Their columns differ too. Both carry `name`/`label`/`description`/`dataType`/
+ * `function`; table columns add `formula` and `isEncrypt`, while view columns add
+ * `isFormula` and `source` (the fully qualified lineage of the underlying
+ * physical column).
+ *
+ * The models are plain data — no classes — so results survive
+ * `structuredClone`, `JSON.stringify`, and a trip through a worker or an HTTP
+ * response. Where Python uses `isinstance`, these use a `kind` discriminant,
+ * which narrows correctly in TypeScript and survives serialisation.
+ *
+ * Every parser tolerates missing keys, so a server-side addition or omission
+ * degrades to a default instead of throwing.
+ */
+
+type Payload = Record<string, unknown>;
+/** Fields common to table and view columns. */
+interface ColumnBase {
+    name: string;
+    label: string;
+    description: string;
+    dataType: string;
+    function: ColumnFunction;
+    /** The untouched API record, for fields this client does not model. */
+    raw: Payload;
+}
+/** A column of a physical table. */
+interface TableColumn extends ColumnBase {
+    kind: "tableColumn";
+    formula: string;
+    isEncrypted: boolean;
+    /** Whether Incorta treats this column as a key. */
+    isKey: boolean;
+}
+/** A column of a business view. */
+interface ViewColumn extends ColumnBase {
+    kind: "viewColumn";
+    /**
+     * Fully qualified lineage of the backing physical column, such as
+     * `"OnlineStore.customer.AccountNumber"`. Empty for formula columns.
+     */
+    source: string;
+    /** Whether the column is computed rather than sourced. */
+    isFormula: boolean;
+}
+type Column = TableColumn | ViewColumn;
+/** Fields common to tables and views. */
+interface SchemaObjectBase {
+    name: string;
+    type: ObjectType;
+    owner: string;
+    description: string;
+    schemaName: string;
+    /** `schema.object` — the form used to address an object in a query. */
+    qualifiedName: string;
+    columnNames: readonly string[];
+    raw: Payload;
+}
+/** A physical table. */
+interface Table extends SchemaObjectBase {
+    kind: "table";
+    columns: readonly TableColumn[];
+    /** Columns Incorta marks as keys. */
+    keys: readonly TableColumn[];
+    /**
+     * Row count as last reported by Incorta; `0` when the table has not been
+     * loaded or the count is unavailable.
+     */
+    rowsCount: number;
+    multiDataSource: boolean;
+    hierarchy: boolean;
+    /** Timestamp of the most recent load, or `null`. */
+    lastVersion: Date | null;
+}
+/** A business view. */
+interface View extends SchemaObjectBase {
+    kind: "view";
+    columns: readonly ViewColumn[];
+    /** The view's base table when Incorta reports one; often empty. */
+    baseTable: string;
+    /** Distinct physical columns this view draws from, in order. */
+    sources: readonly string[];
+}
+type SchemaObject = Table | View;
+/**
+ * Summary of a schema as returned by the schema list endpoint.
+ *
+ * This is the lightweight form: it names the schema but carries no tables or
+ * views. Call `client.schemas.get()` to fetch the contents.
+ */
+interface SchemaInfo {
+    id: number;
+    name: string;
+    description: string;
+    type: string;
+    owner: string;
+    lastModified: Date | null;
+    isEmpty: boolean;
+    isPhysical: boolean;
+    isBusiness: boolean;
+    raw: Payload;
+}
+interface SchemaBase {
+    name: string;
+    total: number;
+    /** Every table or view, whichever this schema holds. */
+    objects: readonly SchemaObject[];
+    objectNames: readonly string[];
+    raw: Payload;
+}
+/** A physical schema, containing tables. */
+interface PhysicalSchema extends SchemaBase {
+    kind: "physical";
+    objects: readonly Table[];
+    tables: readonly Table[];
+}
+/** A business schema, containing views. */
+interface BusinessSchema extends SchemaBase {
+    kind: "business";
+    objects: readonly View[];
+    views: readonly View[];
+}
+type Schema = PhysicalSchema | BusinessSchema;
+/** Looks up a table or view by name, case-insensitively. */
+declare function findObject(schema: Schema, name: string): SchemaObject | undefined;
+/** Looks up one column of a table or view by name, case-insensitively. */
+declare function findColumn(object: SchemaObject, name: string): Column | undefined;
+/** One page of results, plus the paging window that produced it. */
+interface Page<T> {
+    /** The records in this page. */
+    items: readonly T[];
+    /** Total records available server-side, across all pages. */
+    total: number;
+    /** Page size requested; `0` means "no limit" to the API. */
+    limit: number;
+    /** Zero-based index this page started at. */
+    offset: number;
+    /** Whether more records exist beyond this page. */
+    hasMore: boolean;
+}
+
+/**
+ * Schema listing and retrieval.
+ *
+ * Every call is made with the signed-in user's own access token, so results are
+ * already filtered to what that user may see in Incorta — there is no
+ * app-level identity to over-share from.
+ */
+
+/** Page size used by `iterAll` when the caller does not choose one. */
+declare const DEFAULT_PAGE_SIZE = 100;
+interface ListSchemasOptions {
+    /**
+     * `ALL`, `PHYSICAL`, or `BUSINESS`. Validated locally because the API
+     * silently falls back to `BUSINESS` for any unrecognised value instead of
+     * returning an error.
+     * @default "ALL"
+     */
+    type?: SchemaType;
+    /** Maximum schemas to return; `0` means all. @default 0 */
+    limit?: number;
+    /** Zero-based index to start from. @default 0 */
+    offset?: number;
+    /** Result ordering. @default "NAME_ASC" */
+    sortBy?: SortBy;
+}
+interface IterSchemasOptions {
+    type?: SchemaType;
+    /** Records per request; must be positive. @default 100 */
+    pageSize?: number;
+    sortBy?: SortBy;
+}
+interface SchemasResource {
+    /**
+     * Lists the schemas this user can see, without their tables or views.
+     *
+     * @throws {IncortaConfigError} `type` or `sortBy` is not a valid value.
+     */
+    list(options?: ListSchemasOptions): Promise<SchemaInfo[]>;
+    /**
+     * Like {@link list}, but also returns the server-side total. Use it when you
+     * need to know how many schemas exist beyond the current page.
+     */
+    listPage(options?: ListSchemasOptions): Promise<Page<SchemaInfo>>;
+    /**
+     * Yields every schema, fetching one page at a time.
+     *
+     * Preferable to `limit: 0` on large tenants, where a single unbounded
+     * response can be slow and memory-hungry.
+     */
+    iterAll(options?: IterSchemasOptions): AsyncGenerator<SchemaInfo, void, undefined>;
+    /** Lists physical schemas. Shorthand for `list({ type: "PHYSICAL" })`. */
+    physical(options?: Omit<ListSchemasOptions, "type">): Promise<SchemaInfo[]>;
+    /** Lists business schemas. Shorthand for `list({ type: "BUSINESS" })`. */
+    business(options?: Omit<ListSchemasOptions, "type">): Promise<SchemaInfo[]>;
+    /**
+     * Fetches one schema with all of its tables or views.
+     *
+     * Returns a `PhysicalSchema` or a `BusinessSchema` depending on what the
+     * environment reports; switch on `.kind` to narrow.
+     *
+     * @throws {SchemaNotFoundError} No such schema, or this user cannot see it.
+     * @throws {IncortaConfigError} `name` is empty.
+     */
+    get(name: string): Promise<Schema>;
+    /** Whether a schema with this name is visible to this user. */
+    exists(name: string): Promise<boolean>;
+}
+
+interface TablesResource {
+    /**
+     * Fetches one table or view by name.
+     *
+     * Searches physical tables and business views alike, so callers do not need to
+     * know which kind of schema they are addressing. Switch on `.kind`
+     * (`"table"` / `"view"`) to narrow the result.
+     *
+     * @throws {SchemaNotFoundError} The schema does not exist.
+     * @throws {TableNotFoundError} The schema exists but holds no such object.
+     * @throws {IncortaConfigError} `tableName` is empty.
+     */
+    get(schemaName: string, tableName: string): Promise<SchemaObject>;
+    /** Lists every table and view in a schema. */
+    list(schemaName: string): Promise<SchemaObject[]>;
+    /** Lists the names of every table and view in a schema. */
+    names(schemaName: string): Promise<string[]>;
+    /** Fetches the columns of one table or view. */
+    columns(schemaName: string, tableName: string): Promise<Column[]>;
+    /** Whether the named table or view exists in the schema. */
+    exists(schemaName: string, tableName: string): Promise<boolean>;
+    /** Lists only physical tables, skipping views. */
+    tablesOnly(schemaName: string): Promise<Table[]>;
+    /** Lists only business views, skipping tables. */
+    viewsOnly(schemaName: string): Promise<View[]>;
+}
+
+/**
+ * The per-user client.
+ *
+ * Metadata in this SDK is always read *as somebody*: the token comes from an
+ * Incorta OAuth session, so two users of the same app see two different
+ * catalogs. Nothing is cached — every call reads Incorta live, so a schema
+ * changed in Incorta is visible on the next call and no user's catalog can
+ * outlive the request that fetched it.
+ */
+
+/** Non-secret view of a scoped client, safe to log. */
+interface UserClientInfo {
+    baseUrl: string;
+    tenant: string;
+    /** Incorta login name of the user this client acts as, when known. */
+    user: string | undefined;
+    /** Epoch millis when this client's access token expires; `0` when unknown. */
+    accessTokenExpiresAt: number;
+}
+interface IncortaUserClient {
+    /**
+     * The Incorta user this client acts as. `null` for a client built from a
+     * bare access token, where no identity was supplied alongside it.
+     */
+    user: IncortaUser | null;
+    /** Schema listing and retrieval, as this user. */
+    schemas: SchemasResource;
+    /** Table, view, and column retrieval, as this user. */
+    tables: TablesResource;
+    /** Row queries against business views, as this user. */
+    data: DataResource;
+    /**
+     * The resolved configuration, minus the token.
+     *
+     * The token is deliberately absent so that logging the client — or
+     * serialising it into an error report — cannot leak a user's credential.
+     */
+    info: UserClientInfo;
+}
+interface UserClientOptions {
+    /** Resolves the bearer token for each request. */
+    getToken: TokenProvider;
+    /** The identity behind the token, when it is known. */
+    user?: IncortaUser | null;
+    /** Epoch millis the token expires at, for {@link UserClientInfo}. */
+    accessTokenExpiresAt?: number;
+}
+
+/**
+ * Error hierarchy for @incorta/sdk.
+ *
+ * Every failure thrown by this package derives from {@link IncortaError}, so
+ * callers can catch one type and still inspect the Incorta error code when they
+ * need detail.
+ *
+ * The Incorta API reports failures as `{"message": "INC_09030108: Invalid ..."}`.
+ * The `INC_` prefix is a stable machine-readable code; {@link IncortaApiError.code}
+ * exposes it separately from the human-readable remainder.
+ */
+/** Base class for every error thrown by @incorta/sdk. */
+declare class IncortaError extends Error {
+    constructor(message: string);
+}
+/**
+ * The client was configured with missing or invalid values.
+ *
+ * Thrown before any network call, so it always indicates a caller mistake
+ * rather than a server or connectivity problem.
+ */
+declare class IncortaConfigError extends IncortaError {
+    constructor(message: string);
+}
+/**
+ * The request carried no signed-in user.
+ *
+ * Every call in this SDK acts *as* an Incorta user, so there is no anonymous
+ * mode to fall back to. Send the visitor through `auth.handler`'s login route
+ * (or let `auth.gate` do it) and retry once a session exists.
+ */
+declare class IncortaAuthRequiredError extends IncortaError {
+    constructor(message?: string);
+}
+/**
+ * The session's access token expired while the client was still holding it.
+ *
+ * A scoped client captures the token as it stood when the session was read, so
+ * a long-lived one eventually goes stale. Re-read the session
+ * (`client.forRequest(request)` per request) to pick up a refreshed token —
+ * `@incorta/auth` renews it automatically while reading.
+ */
+declare class IncortaSessionExpiredError extends IncortaError {
+    /** Epoch millis at which the captured token expired. */
+    readonly expiredAt: number;
+    constructor(
+    /** Epoch millis at which the captured token expired. */
+    expiredAt: number);
+}
+/** The Incorta environment could not be reached (DNS, TLS, refused connection). */
+declare class IncortaConnectionError extends IncortaError {
+    /** The underlying `fetch` failure, when there was one. */
+    readonly cause?: unknown | undefined;
+    constructor(message: string, 
+    /** The underlying `fetch` failure, when there was one. */
+    cause?: unknown | undefined);
+}
+/** The request exceeded the configured timeout. */
+declare class IncortaTimeoutError extends IncortaConnectionError {
+    constructor(message: string);
+}
+/** The Incorta API returned a non-success HTTP status. */
+declare class IncortaApiError extends IncortaError {
+    /** HTTP status code of the response. */
+    readonly statusCode: number;
+    /** Incorta error code such as `"INC_09030108"`, when the response carried one. */
+    readonly code: string | undefined;
+    /** Human-readable message with the `INC_` prefix stripped. */
+    readonly detail: string;
+    /** Raw response text, truncated for readability. */
+    readonly responseBody: string;
+    /** The request URL. Never carries credentials — the token travels in a header. */
+    readonly url: string | undefined;
+    constructor(statusCode: number, detail: string, options?: {
+        code?: string;
+        responseBody?: string;
+        url?: string;
+    });
+}
+/**
+ * Incorta rejected the user's access token (HTTP 401).
+ *
+ * Distinct from {@link IncortaSessionExpiredError}, which is raised locally
+ * before the request goes out. This one means the token reached Incorta and
+ * came back refused — a revoked session, a client whose registration changed,
+ * or a token minted for a different tenant.
+ */
+declare class AuthenticationError extends IncortaApiError {
+    constructor(...args: ConstructorParameters<typeof IncortaApiError>);
+}
+/**
+ * The user is authenticated but lacks access to the requested resource (403).
+ *
+ * Metadata is read with the signed-in user's own token, so this reflects that
+ * user's Incorta permissions — not a defect in the app's configuration.
+ */
+declare class PermissionDeniedError extends IncortaApiError {
+    constructor(...args: ConstructorParameters<typeof IncortaApiError>);
+}
+/** The requested resource does not exist (HTTP 404). */
+declare class NotFoundError extends IncortaApiError {
+    constructor(...args: ConstructorParameters<typeof IncortaApiError>);
+}
+/** The named schema does not exist, or this user cannot see it. */
+declare class SchemaNotFoundError extends NotFoundError {
+    constructor(...args: ConstructorParameters<typeof IncortaApiError>);
+}
+/** Incorta reported an internal error (HTTP 5xx). */
+declare class IncortaServerError extends IncortaApiError {
+    constructor(...args: ConstructorParameters<typeof IncortaApiError>);
+}
+/**
+ * No table or view with the given name exists in the schema.
+ *
+ * Thrown client-side: the API returns the whole schema in one call, so a
+ * missing table is detected locally rather than by a failed request.
+ */
+declare class TableNotFoundError extends IncortaError {
+    readonly schemaName: string;
+    readonly tableName: string;
+    /** Names that *do* exist in the schema, to make the typo obvious. */
+    readonly available: string[];
+    constructor(schemaName: string, tableName: string, 
+    /** Names that *do* exist in the schema, to make the typo obvious. */
+    available?: string[]);
+}
+
+/** Non-secret view of the resolved configuration, safe to log. */
+interface ClientInfo {
+    baseUrl: string;
+    tenant: string;
+    timeoutMs: number;
+    maxRetries: number;
+}
+interface IncortaClient {
+    /**
+     * The OAuth instance this client reads sessions from.
+     *
+     * Mount `auth.handler` to serve the login routes and `auth.gate` to require
+     * a session, exactly as if you had built it with `createIncortaAuth`
+     * yourself — it is the same object when you passed one in.
+     */
+    auth: IncortaAuth;
+    /**
+     * Builds a client acting as the user behind `request`, reading (and
+     * refreshing) their session.
+     *
+     * The normal entry point: call it per request, so every batch of metadata
+     * calls runs on a freshly refreshed token.
+     *
+     * @throws {IncortaAuthRequiredError} The request carries no session.
+     */
+    forRequest(request: Request): Promise<IncortaUserClient>;
+    /**
+     * Builds a client from a session you already read (via `auth.getSession`, a
+     * framework middleware, or a gate).
+     *
+     * The session's token is captured as-is. `@incorta/auth` refreshes it while
+     * *reading* the session, so hold a scoped client no longer than the request
+     * that produced it; past the token's expiry, calls raise
+     * {@link IncortaSessionExpiredError} rather than 401ing against Incorta.
+     */
+    forSession(session: AuthSession): IncortaUserClient;
+    /**
+     * Builds a client from a raw Incorta access token.
+     *
+     * The escape hatch for tokens that did not arrive as a cookie session — a
+     * bearer header from a mobile or SPA client, or a token minted elsewhere in
+     * the same tenant. Expiry is not tracked here: an expired token fails as a
+     * 401 {@link AuthenticationError} from Incorta.
+     */
+    forAccessToken(accessToken: string, options?: {
+        user?: IncortaUser;
+    }): IncortaUserClient;
+    /** The resolved configuration, minus any secrets. */
+    info: ClientInfo;
+}
+/**
+ * Creates a client for Incorta metadata, authenticated with OAuth 2.0.
+ *
+ * Unlike a personal-access-token client, this one has no identity of its own:
+ * it reads schemas and tables **as the signed-in user**, so results are already
+ * scoped to that user's Incorta permissions. Sessions come from
+ * `@incorta/auth`.
+ *
+ * ```ts
+ * const client = createIncortaClient(); // reads INCORTA_* from the environment
+ *
+ * // Serve the OAuth routes with the auth instance the client owns.
+ * app.use("/auth", toNodeHandler(client.auth.handler));
+ *
+ * app.get("/api/schemas", async (req, res) => {
+ *   const incorta = await client.forRequest(toWebRequest(req));
+ *   res.json(await incorta.schemas.physical());
+ * });
+ * ```
+ *
+ * Pass `auth` when the app already builds its own instance — two instances
+ * would mean two sets of OAuth state for the same users:
+ *
+ * ```ts
+ * const auth = createIncortaAuth({ appAccess: "catalog" });
+ * const client = createIncortaClient({ auth });
+ * ```
+ *
+ * @throws {IncortaConfigError} A required value is missing or malformed.
+ */
+declare function createIncortaClient(config?: IncortaClientConfig): IncortaClient;
+
+export { AGGREGATIONS, type AggregateFilter, type Aggregation, AuthenticationError, type BusinessSchema, COLUMN_FUNCTIONS, type ClientInfo, type Column, type ColumnBase, type ColumnFunction, DEFAULT_PAGE_SIZE, DEFAULT_QUERY_PAGE_SIZE, type DataResource, type Dimension, type DimensionInput, FILTER_OPS, type Filter, type FilterOp, IncortaApiError, IncortaAuthRequiredError, type IncortaClient, type IncortaClientConfig, IncortaConfigError, IncortaConnectionError, IncortaError, IncortaServerError, IncortaSessionExpiredError, IncortaTimeoutError, type IncortaUserClient, type IterSchemasOptions, type ListSchemasOptions, type Measure, type MeasureInput, NULL_VALUE_AS, NotFoundError, type NullValueAs, type ObjectType, type Page, PermissionDeniedError, type PhysicalSchema, QUERY_FORMATS, type QueryFormat, type QueryOptions, type QueryResult, type ResultColumn, SCHEMA_TYPES, SORT_DIRECTIONS, SORT_ORDERS, type Schema, type SchemaInfo, SchemaNotFoundError, type SchemaObject, type SchemaType, type SchemasResource, type Sort, type SortBy, type SortDirection, type Table, type TableColumn, TableNotFoundError, type TablesResource, type UserClientInfo, type UserClientOptions, type View, type ViewColumn, createIncortaClient, findColumn, findObject, parseColumnFunction, parseObjectType, parseQueryResult };