@venizia/ignis-connectors 0.2.0-4 → 0.2.0-40

package/dist/cjs/common/index.d.ts

@@ -0,0 +1,2 @@
+export * from './scope-filter';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/common/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/common/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC"}

package/dist/cjs/common/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./scope-filter"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/common/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/common/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iDAA+B"}

package/dist/cjs/common/scope-filter.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Refuses to boot when `settings.scopeFilter` is declared where it cannot be honoured. Both cases
+ * are silent at runtime and fail in OPPOSITE directions: a search-backed model returns more rows,
+ * a context-less one returns none. The caller supplies `asyncContextEnabled` so no application
+ * config type reaches into this tier.
+ */
+export declare const assertScopeFilterSupported: (opts: {
+    asyncContextEnabled: boolean;
+}) => void;
+//# sourceMappingURL=scope-filter.d.ts.map

package/dist/cjs/common/scope-filter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-filter.d.ts","sourceRoot":"","sources":["../../../src/common/scope-filter.ts"],"names":[],"mappings":"AAKA;;;;;GAKG;AACH,eAAO,MAAM,0BAA0B,GAAI,MAAM;IAAE,mBAAmB,EAAE,OAAO,CAAA;CAAE,KAAG,IA4CnF,CAAC"}

package/dist/cjs/common/scope-filter.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertScopeFilterSupported = void 0;
+const common_1 = require("@venizia/ignis-helpers/common");
+const core_1 = require("@venizia/ignis-helpers/core");
+const ignis_kernel_1 = require("@venizia/ignis-kernel");
+const models_1 = require("../search/core/models");
+/**
+ * Refuses to boot when `settings.scopeFilter` is declared where it cannot be honoured. Both cases
+ * are silent at runtime and fail in OPPOSITE directions: a search-backed model returns more rows,
+ * a context-less one returns none. The caller supplies `asyncContextEnabled` so no application
+ * config type reaches into this tier.
+ */
+const assertScopeFilterSupported = (opts) => {
+    const models = ignis_kernel_1.MetadataRegistry.getInstance().getAllModels();
+    const searchBacked = [];
+    const withoutAmbientContext = [];
+    for (const [name, entry] of models) {
+        if (!entry.metadata?.settings?.scopeFilter) {
+            continue;
+        }
+        const modelClass = (0, common_1.resolveValue)(entry.target);
+        if (modelClass === models_1.BaseSearchEntity || modelClass.prototype instanceof models_1.BaseSearchEntity) {
+            searchBacked.push(name);
+            continue;
+        }
+        if (!opts.asyncContextEnabled) {
+            withoutAmbientContext.push(name);
+        }
+    }
+    if (searchBacked.length > 0) {
+        throw (0, core_1.getError)({
+            message: [
+                `[assertScopeFilterSupported] settings.scopeFilter on a search-backed model | models: ${searchBacked.join(', ')}`,
+                'Search repositories never read this setting, so no row scope is applied.',
+                'Unlike the relational path, a missing scope here returns MORE rows rather than none - nothing fails, the result is just wider.',
+                'Scope the search query in the application, and remove settings.scopeFilter from the model.',
+            ].join(' | '),
+        });
+    }
+    if (withoutAmbientContext.length > 0) {
+        throw (0, core_1.getError)({
+            message: [
+                `[assertScopeFilterSupported] settings.scopeFilter declared while asyncContext.enable is false | models: ${withoutAmbientContext.join(', ')}`,
+                'scopeFilter.resolve() takes no arguments, so the ambient request context is its only input.',
+                'With no context store every resolve() returns undefined, onMissing denies by default, and EVERY query on these models matches zero rows - with nothing naming the flag as the cause.',
+                'Set asyncContext.enable to true, or remove settings.scopeFilter.',
+            ].join(' | '),
+        });
+    }
+};
+exports.assertScopeFilterSupported = assertScopeFilterSupported;
+//# sourceMappingURL=scope-filter.js.map

package/dist/cjs/common/scope-filter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-filter.js","sourceRoot":"","sources":["../../../src/common/scope-filter.ts"],"names":[],"mappings":";;;AAAA,0DAA6D;AAC7D,sDAAuD;AACvD,wDAAyD;AACzD,iDAAwD;AAExD;;;;;GAKG;AACI,MAAM,0BAA0B,GAAG,CAAC,IAAsC,EAAQ,EAAE;IACzF,MAAM,MAAM,GAAG,+BAAgB,CAAC,WAAW,EAAE,CAAC,YAAY,EAAE,CAAC;IAE7D,MAAM,YAAY,GAAa,EAAE,CAAC;IAClC,MAAM,qBAAqB,GAAa,EAAE,CAAC;IAE3C,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,EAAE,CAAC;QACnC,IAAI,CAAC,KAAK,CAAC,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;YAC3C,SAAS;QACX,CAAC;QAED,MAAM,UAAU,GAAG,IAAA,qBAAY,EAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAE9C,IAAI,UAAU,KAAK,yBAAgB,IAAI,UAAU,CAAC,SAAS,YAAY,yBAAgB,EAAE,CAAC;YACxF,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACxB,SAAS;QACX,CAAC;QAED,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC;YAC9B,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnC,CAAC;IACH,CAAC;IAED,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,IAAA,eAAQ,EAAC;YACb,OAAO,EAAE;gBACP,wFAAwF,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;gBACjH,0EAA0E;gBAC1E,gIAAgI;gBAChI,4FAA4F;aAC7F,CAAC,IAAI,CAAC,KAAK,CAAC;SACd,CAAC,CAAC;IACL,CAAC;IAED,IAAI,qBAAqB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrC,MAAM,IAAA,eAAQ,EAAC;YACb,OAAO,EAAE;gBACP,2GAA2G,qBAAqB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;gBAC7I,6FAA6F;gBAC7F,sLAAsL;gBACtL,kEAAkE;aACnE,CAAC,IAAI,CAAC,KAAK,CAAC;SACd,CAAC,CAAC;IACL,CAAC;AACH,CAAC,CAAC;AA5CW,QAAA,0BAA0B,8BA4CrC"}

package/dist/cjs/http/common/types.d.ts

@@ -0,0 +1,62 @@
+import type { TFilter } from '@venizia/ignis-filter';
+/** What a caller hands the resolver seam: the token and, optionally, which provider issued it. */
+export interface IAuthToken {
+    value: string;
+    type?: string;
+    provider?: string;
+}
+/**
+ * Where the token comes from when the datasource was not given one outright.
+ *
+ * A seam, not a guard: a browser resolver reads storage, a server resolver reads a secret, and
+ * neither is baked into the transport. Returning `undefined` means "no token", which is different
+ * from an empty one.
+ */
+export type TAuthTokenResolver = () => IAuthToken | undefined;
+/**
+ * Every shape `Headers` accepts. Not `Record<string, string>`: header names are case-INSENSITIVE,
+ * so a plain object lets two spellings of one name coexist, and merging them APPENDS rather than
+ * overrides - `{ 'x-request-count': 'false', 'X-Request-Count': 'true' }` reaches the wire as
+ * `x-request-count: "false, true"`, which parses as neither.
+ */
+export type THttpHeaders = Headers | Array<[string, string]> | Record<string, string>;
+export interface IHttpDataSourceSettings {
+    baseUrl: string;
+    /** Sent on every request, merged through `Headers` so a caller value overrides a default. */
+    headers?: THttpHeaders;
+    /** A fixed token. Consulted BEFORE `authTokenResolver` - an explicit value is never overridden by a lookup. */
+    authToken?: IAuthToken;
+    authTokenResolver?: TAuthTokenResolver;
+    /**
+     * Runs on a 401, and its ANSWER decides: `true` retries the request once, `false` lets the 401
+     * stand. Absent means no retry at all.
+     *
+     * A hook rather than a boolean, because "recover from a 401" is the host's policy, not the
+     * transport's: one host refreshes a token then retries, another logs the user out, a third does
+     * both in an order only it knows. A boolean could only mean "ask the resolver again", which reads
+     * like recovery and is not - someone would wire it expecting a refresh and get a silent loop.
+     *
+     * The transport's part is the seam and the single retry. Whatever the hook does to make the next
+     * attempt work - refresh, re-login, nothing - happens before it answers, and the retry re-resolves
+     * the token afterwards.
+     */
+    onUnauthorized?: () => Promise<boolean> | boolean;
+}
+/**
+ * One response, with the total kept apart from the rows.
+ *
+ * `hasRange` is the whole point: a list with no `Content-Range` has NO total, which is a different
+ * answer from "the total equals this page". Folding the two is how a count of 7000 reports 1 and
+ * every screen reading it looks healthy.
+ */
+export interface IHttpReadResult<R> {
+    data: R;
+    hasRange: boolean;
+    total?: number;
+    skip?: number;
+    dataLength: number;
+}
+export type THttpQuery<E extends object> = {
+    filter?: TFilter<E>;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/cjs/http/common/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/http/common/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAErD,kGAAkG;AAClG,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,UAAU,GAAG,SAAS,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AACtF,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,MAAM,CAAC;IAEhB,6FAA6F;IAC7F,OAAO,CAAC,EAAE,YAAY,CAAC;IAEvB,+GAA+G;IAC/G,SAAS,CAAC,EAAE,UAAU,CAAC;IAEvB,iBAAiB,CAAC,EAAE,kBAAkB,CAAC;IAEvC;;;;;;;;;;;;OAYG;IACH,cAAc,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CACnD;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,IAAI,EAAE,CAAC,CAAC;IACR,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,IAAI;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;CAAE,CAAC"}

package/dist/cjs/http/common/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/cjs/http/common/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../../src/http/common/types.ts"],"names":[],"mappings":""}

package/dist/cjs/http/datasource.d.ts

@@ -0,0 +1,75 @@
+import { AbstractDataSource } from '@venizia/ignis-kernel/repository';
+import { NodeFetchNetworkRequest } from '@venizia/ignis-helpers/core';
+import type { IAuthToken, IHttpDataSourceSettings, IHttpReadResult } from './common/types';
+/**
+ * A datasource whose transport is HTTP.
+ *
+ * A repository talks to a datasource, and `AbstractDataSource` is engine-neutral - its only required
+ * member is `configure()`. So "a request to another IGNIS server" is a datasource in the same sense
+ * Drizzle-over-Postgres is one: same role, different transport, and the same
+ * `@venizia/ignis-filter` vocabulary on the way in.
+ *
+ * It targets the IGNIS REST contract - a list route that answers `Content-Range` - and promises
+ * nothing about an arbitrary REST API. How a filter serialises and which header carries the total
+ * are one API's CONVENTIONS; IGNIS talking to IGNIS is both ends speaking its own.
+ */
+export declare class HttpDataSource extends AbstractDataSource<IHttpDataSourceSettings> {
+    name: string;
+    settings: IHttpDataSourceSettings;
+    /** A remote API publishes no schema to this process. An empty object where a caller expects table metadata is worse than nothing. */
+    schema: never;
+    /** The framework's own HTTP layer, not a bare `fetch`: timeout, abort, secret redaction and scoped logging come with it, and one HTTP path in the framework beats two. */
+    protected network: NodeFetchNetworkRequest;
+    constructor(opts: IHttpDataSourceSettings & {
+        name?: string;
+    });
+    /** Nothing to open. Holding no connection is what makes this one safe to construct anywhere. */
+    configure(): Promise<void>;
+    /** No transactions over REST. The root probes capabilities rather than assuming them. */
+    getCapabilities(): {
+        transactions: boolean;
+    };
+    /** Explicit token first, resolver only when there is none - a caller that supplied one is never overridden by a lookup. */
+    protected resolveAuthToken(): IAuthToken | undefined;
+    /**
+     * Built through `Headers` rather than a plain object, so a caller's value genuinely OVERRIDES a
+     * default. Two spellings of one name in an object both survive the merge and `Headers` then
+     * APPENDS them - `x-request-count: "false, true"` - which parses as neither.
+     */
+    protected buildHeaders(opts: {
+        token?: IAuthToken;
+    }): Headers;
+    buildUrl(opts: {
+        paths: Array<string>;
+        query?: Record<string, unknown>;
+    }): string;
+    /**
+     * One request, with the total read from `Content-Range` and REPORTED as absent when the header is
+     * not there.
+     *
+     * Goes through {@link HttpDataSource.request}, so auth, the 401 hook and the single retry live in
+     * ONE place - a second header-building path is where a guard gets forgotten.
+     */
+    /**
+     * One request, answered RAW.
+     *
+     * `read` is about rows and cannot express a response that is not JSON - an export endpoint returns
+     * bytes and a filename. Rather than invent a blob shape on the repository, whose contract is rows,
+     * the transport stays reachable: a caller gets the `Response` and reads `.blob()` and
+     * `content-disposition` itself.
+     *
+     * Auth, the 401 hook and the single retry apply here exactly as they do to `read`.
+     */
+    request(opts: {
+        paths: Array<string>;
+        query?: Record<string, unknown>;
+        method?: string;
+    }): Promise<Response>;
+    read<R>(opts: {
+        paths: Array<string>;
+        query?: Record<string, unknown>;
+        /** What the caller asked for. `one` is never unwrapped - see {@link unwrapBody}. */
+        shape?: 'list' | 'one';
+    }): Promise<IHttpReadResult<R>>;
+}
+//# sourceMappingURL=datasource.d.ts.map

package/dist/cjs/http/datasource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"datasource.d.ts","sourceRoot":"","sources":["../../../src/http/datasource.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,kCAAkC,CAAC;AAEtE,OAAO,EAAE,uBAAuB,EAAE,MAAM,6BAA6B,CAAC;AAEtE,OAAO,KAAK,EAAE,UAAU,EAAE,uBAAuB,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAiD3F;;;;;;;;;;;GAWG;AACH,qBAAa,cAAe,SAAQ,kBAAkB,CAAC,uBAAuB,CAAC;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,uBAAuB,CAAC;IAC3C,qIAAqI;IAC5H,MAAM,EAAS,KAAK,CAAC;IAE9B,0KAA0K;IAC1K,SAAS,CAAC,OAAO,EAAE,uBAAuB,CAAC;gBAE/B,IAAI,EAAE,uBAAuB,GAAG;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;IAY7D,gGAAgG;IAC1F,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAEhC,yFAAyF;IAChF,eAAe;;;IAIxB,2HAA2H;IAC3H,SAAS,CAAC,gBAAgB,IAAI,UAAU,GAAG,SAAS;IAIpD;;;;OAIG;IACH,SAAS,CAAC,YAAY,CAAC,IAAI,EAAE;QAAE,KAAK,CAAC,EAAE,UAAU,CAAA;KAAE,GAAG,OAAO;IA4B7D,QAAQ,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,MAAM;IAkBjF;;;;;;OAMG;IACH;;;;;;;;;OASG;IACG,OAAO,CAAC,IAAI,EAAE;QAClB,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,MAAM,CAAC,EAAE,MAAM,CAAC;KACjB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAuBf,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE;QAClB,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;QACrB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,oFAAoF;QACpF,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;KACxB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC;CAsBhC"}

package/dist/cjs/http/datasource.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HttpDataSource = void 0;
+const repository_1 = require("@venizia/ignis-kernel/repository");
+const common_1 = require("@venizia/ignis-helpers/common");
+const core_1 = require("@venizia/ignis-helpers/core");
+const core_2 = require("@venizia/ignis-helpers/core");
+/**
+ * Both list shapes IGNIS itself answers with, told apart by structure.
+ *
+ * `x-request-count` decides it, and its DEFAULT is on (`rest/base.ts`: `?? 'true'`), so an IGNIS
+ * list route answers the count envelope unless asked otherwise. This datasource asks for the bare
+ * array, but a hand-written route that never reaches `normalizeCountData` can still answer the
+ * envelope - so both are accepted rather than one assumed. Treating an envelope as a row is the
+ * failure that reports one record where there were fifty, with no error anywhere.
+ *
+ * The envelope `count` is the rows of THAT response, never the total - the total is only ever in
+ * `Content-Range`.
+ *
+ * `shape` is asked for rather than sniffed. Structure alone cannot tell an envelope from a record
+ * that happens to carry a `data` column and a `count` column, and guessing wrong there unwraps a
+ * row into whatever its `data` field held.
+ */
+const unwrapBody = (opts) => {
+    const { body, shape } = opts;
+    if (shape === 'one' || Array.isArray(body)) {
+        return body;
+    }
+    if (body && typeof body === 'object' && 'data' in body && 'count' in body) {
+        return body.data;
+    }
+    return body;
+};
+/** `items 0-24/137` -> `{ skip: 0, total: 137 }`. Absent or unparseable answers `undefined`, never a guess. */
+const readContentRange = (opts) => {
+    const { header } = opts;
+    if (!header) {
+        return undefined;
+    }
+    const match = header.match(/(\d+)\s*-\s*(\d+)\s*\/\s*(\d+)/);
+    if (!match) {
+        return undefined;
+    }
+    return { skip: Number(match[1]), total: Number(match[3]) };
+};
+/**
+ * A datasource whose transport is HTTP.
+ *
+ * A repository talks to a datasource, and `AbstractDataSource` is engine-neutral - its only required
+ * member is `configure()`. So "a request to another IGNIS server" is a datasource in the same sense
+ * Drizzle-over-Postgres is one: same role, different transport, and the same
+ * `@venizia/ignis-filter` vocabulary on the way in.
+ *
+ * It targets the IGNIS REST contract - a list route that answers `Content-Range` - and promises
+ * nothing about an arbitrary REST API. How a filter serialises and which header carries the total
+ * are one API's CONVENTIONS; IGNIS talking to IGNIS is both ends speaking its own.
+ */
+class HttpDataSource extends repository_1.AbstractDataSource {
+    constructor(opts) {
+        super({ scope: opts.name ?? HttpDataSource.name });
+        /** A remote API publishes no schema to this process. An empty object where a caller expects table metadata is worse than nothing. */
+        this.schema = {};
+        const { name = 'http', ...settings } = opts;
+        this.name = name;
+        this.settings = settings;
+        this.network = new core_1.NodeFetchNetworkRequest({
+            name,
+            networkOptions: { baseUrl: settings.baseUrl },
+        });
+    }
+    /** Nothing to open. Holding no connection is what makes this one safe to construct anywhere. */
+    async configure() { }
+    /** No transactions over REST. The root probes capabilities rather than assuming them. */
+    getCapabilities() {
+        return { transactions: false };
+    }
+    /** Explicit token first, resolver only when there is none - a caller that supplied one is never overridden by a lookup. */
+    resolveAuthToken() {
+        return this.settings.authToken ?? this.settings.authTokenResolver?.();
+    }
+    /**
+     * Built through `Headers` rather than a plain object, so a caller's value genuinely OVERRIDES a
+     * default. Two spellings of one name in an object both survive the merge and `Headers` then
+     * APPENDS them - `x-request-count: "false, true"` - which parses as neither.
+     */
+    buildHeaders(opts) {
+        const { token } = opts;
+        const headers = new Headers();
+        // Asked explicitly: the server default is the count envelope, and a list that answers rows is
+        // one less shape to tell apart. Set FIRST so a caller can override it.
+        headers.set(common_1.HTTP.Headers.REQUEST_COUNT_DATA, 'false');
+        const configured = [...new Headers(this.settings.headers).entries()];
+        for (const [name, value] of configured) {
+            headers.set(name, value);
+        }
+        if (!token) {
+            return headers;
+        }
+        headers.set(common_1.HTTP.Headers.AUTHORIZATION, `${token.type ?? 'Bearer'} ${token.value}`);
+        // Only when there IS one. Setting it unconditionally sends the string "undefined", which a
+        // server reads as a provider by that name.
+        if (token.provider) {
+            headers.set('x-auth-provider', token.provider);
+        }
+        return headers;
+    }
+    buildUrl(opts) {
+        const { paths, query } = opts;
+        // Path joining belongs to the network helper - it already normalises leading slashes and
+        // refuses an unset base url with a catalogued error.
+        const url = new URL(this.network.getRequestUrl({ paths }));
+        const parameters = Object.entries(query ?? {});
+        for (const [key, value] of parameters) {
+            if (value === undefined) {
+                continue;
+            }
+            url.searchParams.set(key, typeof value === 'string' ? value : JSON.stringify(value));
+        }
+        return url.toString();
+    }
+    /**
+     * One request, with the total read from `Content-Range` and REPORTED as absent when the header is
+     * not there.
+     *
+     * Goes through {@link HttpDataSource.request}, so auth, the 401 hook and the single retry live in
+     * ONE place - a second header-building path is where a guard gets forgotten.
+     */
+    /**
+     * One request, answered RAW.
+     *
+     * `read` is about rows and cannot express a response that is not JSON - an export endpoint returns
+     * bytes and a filename. Rather than invent a blob shape on the repository, whose contract is rows,
+     * the transport stays reachable: a caller gets the `Response` and reads `.blob()` and
+     * `content-disposition` itself.
+     *
+     * Auth, the 401 hook and the single retry apply here exactly as they do to `read`.
+     */
+    async request(opts) {
+        const url = this.buildUrl(opts);
+        const send = () => this.network.getNetworkService().send({
+            url,
+            method: (opts.method ?? common_1.HTTP.Methods.GET),
+            headers: this.buildHeaders({ token: this.resolveAuthToken() }),
+        });
+        let response = await send();
+        if (response.status === common_1.HTTP.ResultCodes.RS_4.Unauthorized && this.settings.onUnauthorized) {
+            const shouldRetry = await this.settings.onUnauthorized();
+            if (shouldRetry) {
+                response = await send();
+            }
+        }
+        return response;
+    }
+    async read(opts) {
+        const response = await this.request(opts);
+        if (!response.ok) {
+            throw (0, core_2.getError)({
+                statusCode: response.status,
+                message: `[${this.name}][read] ${response.status} | ${this.buildUrl(opts)}`,
+            });
+        }
+        const body = await response.json();
+        const range = readContentRange({ header: response.headers.get(common_1.HTTP.Headers.CONTENT_RANGE) });
+        const data = unwrapBody({ body, shape: opts.shape ?? 'list' });
+        return {
+            data,
+            hasRange: range !== undefined,
+            total: range?.total,
+            skip: range?.skip,
+            dataLength: Array.isArray(data) ? data.length : 1,
+        };
+    }
+}
+exports.HttpDataSource = HttpDataSource;
+//# sourceMappingURL=datasource.js.map

package/dist/cjs/http/datasource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"datasource.js","sourceRoot":"","sources":["../../../src/http/datasource.ts"],"names":[],"mappings":"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"}

package/dist/cjs/http/index.d.ts

@@ -0,0 +1,4 @@
+export * from './common/types';
+export * from './datasource';
+export * from './repository';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/http/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/http/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,cAAc,cAAc,CAAC;AAC7B,cAAc,cAAc,CAAC"}

package/dist/cjs/http/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./common/types"), exports);
+__exportStar(require("./datasource"), exports);
+__exportStar(require("./repository"), exports);
+//# sourceMappingURL=index.js.map

package/dist/cjs/http/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/http/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iDAA+B;AAC/B,+CAA6B;AAC7B,+CAA6B"}

package/dist/cjs/http/repository.d.ts

@@ -0,0 +1,72 @@
+import { AbstractEntity } from '@venizia/ignis-kernel/repository';
+import type { IReadableRepository, TCount, TDataWithRange, TFilter, TSchemaType, TWhere } from '@venizia/ignis-kernel/repository';
+import type { AnyType } from '@venizia/ignis-helpers/common';
+import type { HttpDataSource } from './datasource';
+/** The entity a remote resource stands for. `AbstractEntity` wants a name and a schema accessor; a resource over HTTP has the first and cannot honestly claim the second. */
+export declare class HttpResourceEntity extends AbstractEntity {
+    getSchema<T = unknown>(_opts: {
+        type: TSchemaType;
+    }): T;
+}
+/**
+ * Read access to one remote resource, through {@link HttpDataSource}.
+ *
+ * `IReadableRepository` rather than `AbstractRepository`: the abstract class demands twelve members,
+ * so a resource that cannot be written would have to stub `create`, `updateById` and `deleteById`
+ * with throws. Five real methods say more than twelve where seven are lies.
+ *
+ * Every query leaves as the `@venizia/ignis-filter` vocabulary - the same language an IGNIS
+ * repository speaks to Drizzle. One query language, two transports.
+ */
+export declare class HttpRepository<E extends object = AnyType> implements IReadableRepository<E, {}> {
+    dataSource: HttpDataSource;
+    entity: AbstractEntity;
+    protected resource: string;
+    /** An API that publishes a count route names it here. Absent, the total comes from `Content-Range`. */
+    protected countPath?: string;
+    constructor(opts: {
+        dataSource: HttpDataSource;
+        resource: string;
+        countPath?: string;
+    });
+    getEntity(): AbstractEntity;
+    /**
+     * How many rows match, asked of the list route rather than of one that may not exist.
+     *
+     * The default reads the total out of `Content-Range` - MECHANISM, because a route that pages at
+     * all reports what it is paging over. A dedicated count route is CONVENTION: one API publishes
+     * `/count`, another `/search/count`, another deleted it and told callers to read the header. So it
+     * is opt-in through `countPath`.
+     *
+     * With no header there is NO total, and this says so rather than answering with the page size - a
+     * count of 1 for a table of 7000 reads as healthy in every screen that consumes it.
+     */
+    count(opts: {
+        where: TWhere<E>;
+        options?: {};
+    }): Promise<TCount>;
+    existsWith(opts: {
+        where: TWhere<E>;
+        options?: {};
+    }): Promise<boolean>;
+    find<R = E>(opts: {
+        filter: TFilter<E>;
+        options: {
+            shouldQueryRange: true;
+        };
+    }): Promise<TDataWithRange<R>>;
+    find<R = E>(opts: {
+        filter?: TFilter<E>;
+        options?: {};
+    }): Promise<Array<R>>;
+    findOne<R = E>(opts: {
+        filter?: TFilter<E>;
+        options?: {};
+    }): Promise<R | null>;
+    findById<R = E>(opts: {
+        id: string | number;
+        filter?: TFilter<E>;
+        options?: {};
+    }): Promise<R | null>;
+}
+//# sourceMappingURL=repository.d.ts.map

package/dist/cjs/http/repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../../src/http/repository.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAkB,MAAM,kCAAkC,CAAC;AAClF,OAAO,KAAK,EACV,mBAAmB,EACnB,MAAM,EACN,cAAc,EACd,OAAO,EACP,WAAW,EACX,MAAM,EACP,MAAM,kCAAkC,CAAC;AAE1C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AAC7D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAEnD,6KAA6K;AAC7K,qBAAa,kBAAmB,SAAQ,cAAc;IACpD,SAAS,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE;QAAE,IAAI,EAAE,WAAW,CAAA;KAAE,GAAG,CAAC;CAGxD;AAED;;;;;;;;;GASG;AACH,qBAAa,cAAc,CAAC,CAAC,SAAS,MAAM,GAAG,OAAO,CAAE,YAAW,mBAAmB,CAAC,CAAC,EAAE,EAAE,CAAC;IAC3F,UAAU,EAAE,cAAc,CAAC;IAC3B,MAAM,EAAE,cAAc,CAAC;IAEvB,SAAS,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC3B,uGAAuG;IACvG,SAAS,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;gBAEjB,IAAI,EAAE;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE;IAOtF,SAAS,IAAI,cAAc;IAI3B;;;;;;;;;;OAUG;IACG,KAAK,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IA0BhE,UAAU,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC;IAWtE,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE;QACtB,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;QACnB,OAAO,EAAE;YAAE,gBAAgB,EAAE,IAAI,CAAA;SAAE,CAAC;KACrC,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IACxB,IAAI,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAgC3E,OAAO,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;QAAC,OAAO,CAAC,EAAE,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;IAK9E,QAAQ,CAAC,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE;QAC1B,EAAE,EAAE,MAAM,GAAG,MAAM,CAAC;QACpB,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;QACpB,OAAO,CAAC,EAAE,EAAE,CAAC;KACd,GAAG,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC;CAStB"}