@forestadmin/agent-bff 1.5.0 → 1.7.0

package/dist/adapters/console-metrics.d.ts

@@ -0,0 +1,4 @@
+import type { Logger } from '../ports/logger-port';
+import type { Metrics } from '../ports/metrics-port';
+export default function createConsoleMetrics(logger?: Logger): Metrics;
+//# sourceMappingURL=console-metrics.d.ts.map

package/dist/adapters/console-metrics.js

@@ -0,0 +1,18 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = createConsoleMetrics;
+const console_logger_1 = __importDefault(require("./console-logger"));
+function createConsoleMetrics(logger = (0, console_logger_1.default)()) {
+    return {
+        increment(name, tags) {
+            logger('Info', 'metric.increment', { metric: name, ...(tags ?? {}) });
+        },
+        gauge(name, value, tags) {
+            logger('Info', 'metric.gauge', { metric: name, value, ...(tags ?? {}) });
+        },
+    };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY29uc29sZS1tZXRyaWNzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2FkYXB0ZXJzL2NvbnNvbGUtbWV0cmljcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7OztBQUtBLHVDQVNDO0FBWEQsc0VBQW1EO0FBRW5ELFNBQXdCLG9CQUFvQixDQUFDLFNBQWlCLElBQUEsd0JBQW1CLEdBQUU7SUFDakYsT0FBTztRQUNMLFNBQVMsQ0FBQyxJQUFZLEVBQUUsSUFBaUI7WUFDdkMsTUFBTSxDQUFDLE1BQU0sRUFBRSxrQkFBa0IsRUFBRSxFQUFFLE1BQU0sRUFBRSxJQUFJLEVBQUUsR0FBRyxDQUFDLElBQUksSUFBSSxFQUFFLENBQUMsRUFBRSxDQUFDLENBQUM7UUFDeEUsQ0FBQztRQUNELEtBQUssQ0FBQyxJQUFZLEVBQUUsS0FBYSxFQUFFLElBQWlCO1lBQ2xELE1BQU0sQ0FBQyxNQUFNLEVBQUUsY0FBYyxFQUFFLEVBQUUsTUFBTSxFQUFFLElBQUksRUFBRSxLQUFLLEVBQUUsR0FBRyxDQUFDLElBQUksSUFBSSxFQUFFLENBQUMsRUFBRSxDQUFDLENBQUM7UUFDM0UsQ0FBQztLQUNGLENBQUM7QUFDSixDQUFDIn0=

package/dist/adapters/safe-metrics.d.ts

@@ -0,0 +1,8 @@
+import type { Metrics } from '../ports/metrics-port';
+/**
+ * Wraps a Metrics port so emitting a metric can never throw into business logic. Metrics is a
+ * user-supplied implementation; a backend that throws must not break a request (e.g. a throwing
+ * gauge on the schema cache-hit path would otherwise degrade every read).
+ */
+export default function safeMetrics(metrics: Metrics): Metrics;
+//# sourceMappingURL=safe-metrics.d.ts.map

package/dist/adapters/safe-metrics.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = safeMetrics;
+/**
+ * Wraps a Metrics port so emitting a metric can never throw into business logic. Metrics is a
+ * user-supplied implementation; a backend that throws must not break a request (e.g. a throwing
+ * gauge on the schema cache-hit path would otherwise degrade every read).
+ */
+function safeMetrics(metrics) {
+    return {
+        increment(name, tags) {
+            try {
+                metrics.increment(name, tags);
+            }
+            catch {
+                // Swallow: a metrics-backend failure must never break business logic.
+            }
+        },
+        gauge(name, value, tags) {
+            try {
+                metrics.gauge(name, value, tags);
+            }
+            catch {
+                // Swallow: a metrics-backend failure must never break business logic.
+            }
+        },
+    };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoic2FmZS1tZXRyaWNzLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL2FkYXB0ZXJzL3NhZmUtbWV0cmljcy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQU9BLDhCQWlCQztBQXRCRDs7OztHQUlHO0FBQ0gsU0FBd0IsV0FBVyxDQUFDLE9BQWdCO0lBQ2xELE9BQU87UUFDTCxTQUFTLENBQUMsSUFBWSxFQUFFLElBQWlCO1lBQ3ZDLElBQUksQ0FBQztnQkFDSCxPQUFPLENBQUMsU0FBUyxDQUFDLElBQUksRUFBRSxJQUFJLENBQUMsQ0FBQztZQUNoQyxDQUFDO1lBQUMsTUFBTSxDQUFDO2dCQUNQLHNFQUFzRTtZQUN4RSxDQUFDO1FBQ0gsQ0FBQztRQUNELEtBQUssQ0FBQyxJQUFZLEVBQUUsS0FBYSxFQUFFLElBQWlCO1lBQ2xELElBQUksQ0FBQztnQkFDSCxPQUFPLENBQUMsS0FBSyxDQUFDLElBQUksRUFBRSxLQUFLLEVBQUUsSUFBSSxDQUFDLENBQUM7WUFDbkMsQ0FBQztZQUFDLE1BQU0sQ0FBQztnQkFDUCxzRUFBc0U7WUFDeEUsQ0FBQztRQUNILENBQUM7S0FDRixDQUFDO0FBQ0osQ0FBQyJ9

package/dist/cli-core.js

@@ -16,6 +16,7 @@ const auth_mode_middleware_1 = __importDefault(require("./auth/auth-mode-middlew
 const env_config_1 = require("./config/env-config");
 const cors_middleware_1 = __importDefault(require("./cors/cors-middleware"));
 const per_key_origin_1 = __importDefault(require("./cors/per-key-origin"));
+const data_routes_middleware_1 = __importDefault(require("./data/data-routes-middleware"));
 const errors_1 = require("./errors");
 const bff_http_error_1 = require("./http/bff-http-error");
 const bff_http_server_1 = __importDefault(require("./http/bff-http-server"));
@@ -24,6 +25,7 @@ const forest_server_client_1 = __importDefault(require("./oauth/forest-server-cl
 const oauth_routes_1 = __importDefault(require("./oauth/oauth-routes"));
 const session_store_1 = __importDefault(require("./oauth/session-store"));
 const token_cipher_1 = __importDefault(require("./oauth/token-cipher"));
+const create_read_model_1 = __importDefault(require("./read-model/create-read-model"));
 const timezone_middleware_1 = __importDefault(require("./timezone/timezone-middleware"));
 const version_1 = __importDefault(require("./version"));
 const BODY_LIMIT = '16kb';
@@ -109,6 +111,19 @@ function buildApiKeyMiddleware(config, logger) {
     });
     return (0, api_key_middleware_1.default)({ authenticator, logger });
 }
+function buildDataRoutesMiddleware(config, logger) {
+    const apiKeyConfig = resolveApiKeyConfig(config);
+    if (!apiKeyConfig || !config.agentUrl) {
+        logger('Warn', 'Data endpoints disabled: AGENT_URL or read-model configuration is missing');
+        return (0, agent_stub_1.default)();
+    }
+    const { store } = (0, create_read_model_1.default)({
+        forestServerUrl: apiKeyConfig.forestServerUrl,
+        envSecret: apiKeyConfig.forestEnvSecret,
+        logger,
+    });
+    return (0, data_routes_middleware_1.default)({ store, agentUrl: config.agentUrl, logger });
+}
 function buildAgentMiddlewares(config, logger) {
     const { forestAuthSecret, defaultTimezone } = config;
     if (!forestAuthSecret) {
@@ -121,7 +136,7 @@ function buildAgentMiddlewares(config, logger) {
         apiKeyStep,
         (0, per_key_origin_1.default)(),
         (0, timezone_middleware_1.default)({ defaultTimezone }),
-        (0, agent_stub_1.default)(),
+        buildDataRoutesMiddleware(config, logger),
     ];
     return chain.map(agentScoped);
 }
@@ -156,4 +171,4 @@ function reportFatalError(err) {
     process.stderr.write(`Error: ${(0, errors_1.extractErrorMessage)(err)}\n`);
     process.exitCode = 1;
 }
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xpLWNvcmUuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvY2xpLWNvcmUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7QUFnTEEseUJBa0NDO0FBRUQsNENBR0M7QUFuTkQsZ0RBQTZDO0FBRTdDLCtFQUE0RDtBQUM1RCxvRUFBMkQ7QUFDM0QsNEZBQXdFO0FBQ3hFLDhFQUFvRDtBQUNwRCxzRkFBa0U7QUFDbEUsNEVBQXlEO0FBQ3pELHVGQUFtRTtBQUNuRSxvREFBa0Q7QUFDbEQsNkVBQTBEO0FBQzFELDJFQUFpRTtBQUNqRSxxQ0FBK0M7QUFDL0MsMERBQXFEO0FBQ3JELDZFQUFtRDtBQUNuRCwrRUFBNEQ7QUFDNUQsd0ZBQThEO0FBQzlELHdFQUFxRDtBQUNyRCwwRUFBK0Q7QUFDL0Qsd0VBQXFEO0FBQ3JELHlGQUFzRTtBQUN0RSx3REFBZ0M7QUFFaEMsTUFBTSxVQUFVLEdBQUcsTUFBTSxDQUFDO0FBQzFCLE1BQU0sbUJBQW1CLEdBQUcsRUFBRSxHQUFHLEVBQUUsR0FBRyxFQUFFLENBQUM7QUFFekMsU0FBUyxXQUFXLENBQUMsSUFBWTtJQUMvQixPQUFPLElBQUksS0FBSyxRQUFRLElBQUksSUFBSSxDQUFDLFVBQVUsQ0FBQyxTQUFTLENBQUMsQ0FBQztBQUN6RCxDQUFDO0FBRUQsU0FBUyxXQUFXLENBQUMsVUFBc0I7SUFDekMsT0FBTyxLQUFLLFVBQVUsTUFBTSxDQUFDLEdBQUcsRUFBRSxJQUFJO1FBQ3BDLElBQUksQ0FBQyxXQUFXLENBQUMsR0FBRyxDQUFDLElBQUksQ0FBQyxFQUFFLENBQUM7WUFDM0IsTUFBTSxJQUFJLEVBQUUsQ0FBQztZQUViLE9BQU87UUFDVCxDQUFDO1FBRUQsTUFBTSxVQUFVLENBQUMsR0FBRyxFQUFFLElBQUksQ0FBQyxDQUFDO0lBQzlCLENBQUMsQ0FBQztBQUNKLENBQUM7QUFFRCxTQUFTLDRCQUE0QixDQUFDLE1BQWM7SUFDbEQsT0FBTyxLQUFLLFVBQVUsc0JBQXNCLENBQUMs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
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiY2xpLWNvcmUuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9zcmMvY2xpLWNvcmUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7QUFvTUEseUJBa0NDO0FBRUQsNENBR0M7QUF2T0QsZ0RBQTZDO0FBRTdDLCtFQUE0RDtBQUM1RCxvRUFBMkQ7QUFDM0QsNEZBQXdFO0FBQ3hFLDhFQUFvRDtBQUNwRCxzRkFBa0U7QUFDbEUsNEVBQXlEO0FBQ3pELHVGQUFtRTtBQUNuRSxvREFBa0Q7QUFDbEQsNkVBQTBEO0FBQzFELDJFQUFpRTtBQUNqRSwyRkFBdUU7QUFDdkUscUNBQStDO0FBQy9DLDBEQUFxRDtBQUNyRCw2RUFBbUQ7QUFDbkQsK0VBQTREO0FBQzVELHdGQUE4RDtBQUM5RCx3RUFBcUQ7QUFDckQsMEVBQStEO0FBQy9ELHdFQUFxRDtBQUNyRCx1RkFBNkQ7QUFDN0QseUZBQXNFO0FBQ3RFLHdEQUFnQztBQUVoQyxNQUFNLFVBQVUsR0FBRyxNQUFNLENBQUM7QUFDMUIsTUFBTSxtQkFBbUIsR0FBRyxFQUFFLEdBQUcsRUFBRSxHQUFHLEVBQUUsQ0FBQztBQUV6QyxTQUFTLFdBQVcsQ0FBQyxJQUFZO0lBQy9CLE9BQU8sSUFBSSxLQUFLLFFBQVEsSUFBSSxJQUFJLENBQUMsVUFBVSxDQUFDLFNBQVMsQ0FBQyxDQUFDO0FBQ3pELENBQUM7QUFFRCxTQUFTLFdBQVcsQ0FBQyxVQUFzQjtJQUN6QyxPQUFPLEtBQUssVUFBVSxNQUFNLENBQUMsR0FBRyxFQUFFLElBQUk7UUFDcEMsSUFBSSxDQUFDLFdBQVcsQ0FBQyxHQUFHLENBQUMsSUFBSSxDQUFDLEVBQUUsQ0FBQztZQUMzQixNQUFNLElBQUksRUFBRSxDQUFDO1lBRWIsT0FBTztRQUNULENBQUM7UUFFRCxNQUFNLFVBQVUsQ0FBQyxHQUFHLEVBQUUsSUFBSSxDQUFDLENBQUM7SUFDOUIsQ0FBQyxDQUFDO0FBQ0osQ0FBQztBQUVELFNBQVMsNEJBQTRCLENBQUMsTUFBYztJQUNsRCxP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

package/dist/data/agent-data-client.d.ts

@@ -0,0 +1,17 @@
+export interface AgentDataClientOptions {
+    agentUrl: string;
+    token: string;
+}
+export interface AgentDataClient {
+    list(collection: string, query: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    countRaw(collection: string, query: Record<string, unknown>): Promise<unknown>;
+    listRelation(collection: string, parentId: string, relation: string, query: Record<string, unknown>): Promise<Record<string, unknown>[]>;
+    countRelationRaw(collection: string, parentId: string, relation: string, query: Record<string, unknown>): Promise<unknown>;
+}
+/**
+ * Thin data client bound to a request's agent token. Uses the raw `HttpRequester` (not `Collection`)
+ * so the BFF controls the query params — notably the resolved `timezone` — and can read the count
+ * endpoint's raw payload, which `collection.count()` coerces through `Number()` and loses.
+ */
+export default function createAgentDataClient({ agentUrl, token, }: AgentDataClientOptions): AgentDataClient;
+//# sourceMappingURL=agent-data-client.d.ts.map

package/dist/data/agent-data-client.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = createAgentDataClient;
+const agent_client_1 = require("@forestadmin/agent-client");
+/**
+ * Thin data client bound to a request's agent token. Uses the raw `HttpRequester` (not `Collection`)
+ * so the BFF controls the query params — notably the resolved `timezone` — and can read the count
+ * endpoint's raw payload, which `collection.count()` coerces through `Number()` and loses.
+ */
+function createAgentDataClient({ agentUrl, token, }) {
+    const requester = new agent_client_1.HttpRequester(token, { url: agentUrl });
+    // Segments are passed raw: HttpRequester.buildUrl already runs the whole path through
+    // escapeUrlSlug/encodeURI, so pre-encoding here would double-encode (`|` -> `%257C`).
+    const relationPath = (collection, parentId, relation) => `/forest/${collection}/${parentId}/relationships/${relation}`;
+    return {
+        list: (collection, query) => requester.query({ method: 'get', path: `/forest/${collection}`, query }),
+        countRaw: (collection, query) => requester.query({
+            method: 'get',
+            path: `/forest/${collection}/count`,
+            query,
+            skipDeserialization: true,
+        }),
+        listRelation: (collection, parentId, relation, query) => requester.query({ method: 'get', path: relationPath(collection, parentId, relation), query }),
+        countRelationRaw: (collection, parentId, relation, query) => requester.query({
+            method: 'get',
+            path: `${relationPath(collection, parentId, relation)}/count`,
+            query,
+            skipDeserialization: true,
+        }),
+    };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYWdlbnQtZGF0YS1jbGllbnQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvZGF0YS9hZ2VudC1kYXRhLWNsaWVudC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQTZCQSx3Q0ErQkM7QUE1REQsNERBQTBEO0FBd0IxRDs7OztHQUlHO0FBQ0gsU0FBd0IscUJBQXFCLENBQUMsRUFDNUMsUUFBUSxFQUNSLEtBQUssR0FDa0I7SUFDdkIsTUFBTSxTQUFTLEdBQUcsSUFBSSw0QkFBYSxDQUFDLEtBQUssRUFBRSxFQUFFLEdBQUcsRUFBRSxRQUFRLEVBQUUsQ0FBQyxDQUFDO0lBRTlELHNGQUFzRjtJQUN0RixzRkFBc0Y7SUFDdEYsTUFBTSxZQUFZLEdBQUcsQ0FBQyxVQUFrQixFQUFFLFFBQWdCLEVBQUUsUUFBZ0IsRUFBRSxFQUFFLENBQzlFLFdBQVcsVUFBVSxJQUFJLFFBQVEsa0JBQWtCLFFBQVEsRUFBRSxDQUFDO0lBRWhFLE9BQU87UUFDTCxJQUFJLEVBQUUsQ0FBQyxVQUFVLEVBQUUsS0FBSyxFQUFFLEVBQUUsQ0FDMUIsU0FBUyxDQUFDLEtBQUssQ0FBQyxFQUFFLE1BQU0sRUFBRSxLQUFLLEVBQUUsSUFBSSxFQUFFLFdBQVcsVUFBVSxFQUFFLEVBQUUsS0FBSyxFQUFFLENBQUM7UUFDMUUsUUFBUSxFQUFFLENBQUMsVUFBVSxFQUFFLEtBQUssRUFBRSxFQUFFLENBQzlCLFNBQVMsQ0FBQyxLQUFLLENBQUM7WUFDZCxNQUFNLEVBQUUsS0FBSztZQUNiLElBQUksRUFBRSxXQUFXLFVBQVUsUUFBUTtZQUNuQyxLQUFLO1lBQ0wsbUJBQW1CLEVBQUUsSUFBSTtTQUMxQixDQUFDO1FBQ0osWUFBWSxFQUFFLENBQUMsVUFBVSxFQUFFLFFBQVEsRUFBRSxRQUFRLEVBQUUsS0FBSyxFQUFFLEVBQUUsQ0FDdEQsU0FBUyxDQUFDLEtBQUssQ0FBQyxFQUFFLE1BQU0sRUFBRSxLQUFLLEVBQUUsSUFBSSxFQUFFLFlBQVksQ0FBQyxVQUFVLEVBQUUsUUFBUSxFQUFFLFFBQVEsQ0FBQyxFQUFFLEtBQUssRUFBRSxDQUFDO1FBQy9GLGdCQUFnQixFQUFFLENBQUMsVUFBVSxFQUFFLFFBQVEsRUFBRSxRQUFRLEVBQUUsS0FBSyxFQUFFLEVBQUUsQ0FDMUQsU0FBUyxDQUFDLEtBQUssQ0FBQztZQUNkLE1BQU0sRUFBRSxLQUFLO1lBQ2IsSUFBSSxFQUFFLEdBQUcsWUFBWSxDQUFDLFVBQVUsRUFBRSxRQUFRLEVBQUUsUUFBUSxDQUFDLFFBQVE7WUFDN0QsS0FBSztZQUNMLG1CQUFtQixFQUFFLElBQUk7U0FDMUIsQ0FBQztLQUNMLENBQUM7QUFDSixDQUFDIn0=

package/dist/data/agent-query.d.ts

@@ -0,0 +1,36 @@
+export interface BffSortClause {
+    field: string;
+    direction?: 'asc' | 'desc';
+}
+export interface BffPage {
+    limit: number;
+    offset: number;
+}
+export interface ListRequestBody {
+    filter?: unknown;
+    projection?: string[];
+    sort?: BffSortClause[];
+    page?: BffPage;
+}
+export interface CountRequestBody {
+    filter?: unknown;
+}
+export type RelationListRequestBody = ListRequestBody & {
+    parentId: string;
+};
+export type RelationCountRequestBody = CountRequestBody & {
+    parentId: string;
+};
+export type AgentQuery = Record<string, unknown> & {
+    timezone: string;
+};
+export declare function parseListRequest(body: unknown): ListRequestBody;
+export declare function parseCountRequest(body: unknown): CountRequestBody;
+export declare function buildListAgentQuery(collection: string, timezone: string, body: ListRequestBody): AgentQuery;
+export declare function buildCountAgentQuery(timezone: string, body: CountRequestBody): AgentQuery;
+export declare function collectListFieldPaths(body: ListRequestBody): string[];
+export declare function parseParentId(parentId: unknown): string;
+export declare function parseRelationListRequest(body: unknown): RelationListRequestBody;
+export declare function parseRelationCountRequest(body: unknown): RelationCountRequestBody;
+export declare function collectCountFieldPaths(body: CountRequestBody): string[];
+//# sourceMappingURL=agent-query.d.ts.map

package/dist/data/agent-query.js

@@ -0,0 +1,144 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseListRequest = parseListRequest;
+exports.parseCountRequest = parseCountRequest;
+exports.buildListAgentQuery = buildListAgentQuery;
+exports.buildCountAgentQuery = buildCountAgentQuery;
+exports.collectListFieldPaths = collectListFieldPaths;
+exports.parseParentId = parseParentId;
+exports.parseRelationListRequest = parseRelationListRequest;
+exports.parseRelationCountRequest = parseRelationCountRequest;
+exports.collectCountFieldPaths = collectCountFieldPaths;
+const bff_local_errors_1 = require("../http/bff-local-errors");
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// Validate the untyped request body before it reaches the query builders, so malformed shapes
+// (e.g. `projection` or `sort` as a string) surface as 400 invalid_request rather than a 500 from
+// an array method blowing up downstream.
+function parseListRequest(body) {
+    if (!isPlainObject(body))
+        throw (0, bff_local_errors_1.invalidRequest)('Request body must be an object');
+    const { filter, projection, sort, page } = body;
+    if (projection !== undefined) {
+        if (!Array.isArray(projection) || projection.some(field => typeof field !== 'string')) {
+            throw (0, bff_local_errors_1.invalidRequest)('projection must be an array of field names');
+        }
+    }
+    if (sort !== undefined) {
+        const valid = Array.isArray(sort) &&
+            sort.every(clause => isPlainObject(clause) &&
+                typeof clause.field === 'string' &&
+                (clause.direction === undefined ||
+                    clause.direction === 'asc' ||
+                    clause.direction === 'desc'));
+        if (!valid)
+            throw (0, bff_local_errors_1.invalidRequest)('sort must be an array of { field, direction? }');
+    }
+    if (filter !== undefined && !isPlainObject(filter)) {
+        throw (0, bff_local_errors_1.invalidRequest)('filter must be an object');
+    }
+    if (page !== undefined) {
+        if (!isPlainObject(page)) {
+            throw (0, bff_local_errors_1.invalidRequest)('page must be an object with limit and offset');
+        }
+        if (!Number.isInteger(page.limit) || page.limit <= 0) {
+            throw (0, bff_local_errors_1.invalidRequest)('page.limit must be a positive integer');
+        }
+        if (!Number.isInteger(page.offset) || page.offset < 0) {
+            throw (0, bff_local_errors_1.invalidRequest)('page.offset must be a non-negative integer');
+        }
+    }
+    return body;
+}
+function parseCountRequest(body) {
+    if (!isPlainObject(body))
+        throw (0, bff_local_errors_1.invalidRequest)('Request body must be an object');
+    if (body.filter !== undefined && !isPlainObject(body.filter)) {
+        throw (0, bff_local_errors_1.invalidRequest)('filter must be an object');
+    }
+    return body;
+}
+function isBranch(node) {
+    return (typeof node === 'object' &&
+        node !== null &&
+        Array.isArray(node.conditions));
+}
+function isLeaf(node) {
+    return (typeof node === 'object' &&
+        node !== null &&
+        typeof node.field === 'string');
+}
+function collectFilterFields(filter, acc) {
+    if (isBranch(filter)) {
+        filter.conditions.forEach(condition => collectFilterFields(condition, acc));
+    }
+    else if (isLeaf(filter)) {
+        acc.push(filter.field);
+    }
+}
+function serializeSort(sort) {
+    return sort.map(({ field, direction }) => (direction === 'desc' ? `-${field}` : field)).join(',');
+}
+// `parseListRequest` guarantees `limit` > 0 and `offset` >= 0 are integers; this only enforces the
+// page-model rule. The agent paginates by page number/size, so an arbitrary offset that is not a
+// whole multiple of the limit cannot be expressed — reject it rather than return a shifted window.
+function serializePage(page) {
+    const { limit, offset } = page;
+    if (offset % limit !== 0) {
+        throw (0, bff_local_errors_1.invalidRequest)(`page.offset (${offset}) must be a multiple of page.limit (${limit})`);
+    }
+    return { 'page[size]': limit, 'page[number]': offset / limit + 1 };
+}
+function buildListAgentQuery(collection, timezone, body) {
+    const query = { timezone };
+    if (body.filter !== undefined)
+        query.filters = JSON.stringify(body.filter);
+    if (body.projection?.length)
+        query[`fields[${collection}]`] = body.projection.join(',');
+    if (body.sort?.length)
+        query.sort = serializeSort(body.sort);
+    if (body.page)
+        Object.assign(query, serializePage(body.page));
+    return query;
+}
+function buildCountAgentQuery(timezone, body) {
+    const query = { timezone };
+    if (body.filter !== undefined)
+        query.filters = JSON.stringify(body.filter);
+    return query;
+}
+function collectListFieldPaths(body) {
+    const paths = [...(body.projection ?? [])];
+    collectFilterFields(body.filter, paths);
+    (body.sort ?? []).forEach(({ field }) => paths.push(field));
+    return paths;
+}
+// The parent record id is opaque: a packed/composite id must survive unchanged, so its content is
+// never inspected — only presence and primitive type. A finite number (single numeric pk) is
+// coerced to string; anything else is a BFF-local 400 with no agent call.
+function parseParentId(parentId) {
+    if (typeof parentId === 'string') {
+        if (parentId.trim() === '')
+            throw (0, bff_local_errors_1.invalidRequest)('parentId must not be empty');
+        return parentId;
+    }
+    if (typeof parentId === 'number' && Number.isFinite(parentId)) {
+        return String(parentId);
+    }
+    throw (0, bff_local_errors_1.invalidRequest)('parentId is required and must be a non-empty string or a number');
+}
+function parseRelationListRequest(body) {
+    const parentId = parseParentId(body?.parentId);
+    return { ...parseListRequest(body), parentId };
+}
+function parseRelationCountRequest(body) {
+    const parentId = parseParentId(body?.parentId);
+    return { ...parseCountRequest(body), parentId };
+}
+function collectCountFieldPaths(body) {
+    const paths = [];
+    collectFilterFields(body.filter, paths);
+    return paths;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiYWdlbnQtcXVlcnkuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi9zcmMvZGF0YS9hZ2VudC1xdWVyeS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQW9DQSw0Q0E0Q0M7QUFFRCw4Q0FRQztBQW1ERCxrREFhQztBQUVELG9EQU1DO0FBRUQsc0RBTUM7QUFLRCxzQ0FZQztBQUVELDREQUlDO0FBRUQsOERBSUM7QUFFRCx3REFLQztBQTlNRCwrREFBMEQ7QUE2QjFELFNBQVMsYUFBYSxDQUFDLEtBQWM7SUFDbkMsT0FBTyxPQUFPLEtBQUssS0FBSyxRQUFRLElBQUksS0FBSyxLQUFLLElBQUksSUFBSSxDQUFDLEtBQUssQ0FBQyxPQUFPLENBQUMsS0FBSyxDQUFDLENBQUM7QUFDOUUsQ0FBQztBQUVELDhGQUE4RjtBQUM5RixrR0FBa0c7QUFDbEcseUNBQXlDO0FBQ3pDLFNBQWdCLGdCQUFnQixDQUFDLElBQWE7SUFDNUMsSUFBSSxDQUFDLGFBQWEsQ0FBQyxJQUFJLENBQUM7UUFBRSxNQUFNLElBQUEsaUNBQWMsRUFBQyxnQ0FBZ0MsQ0FBQyxDQUFDO0lBRWpGLE1BQU0sRUFBRSxNQUFNLEVBQUUsVUFBVSxFQUFFLElBQUksRUFBRSxJQUFJLEVBQUUsR0FBRyxJQUFJLENBQUM7SUFFaEQsSUFBSSxVQUFVLEtBQUssU0FBUyxFQUFFLENBQUM7UUFDN0IsSUFBSSxDQUFDLEtBQUssQ0FBQyxPQUFPLENBQUMsVUFBVSxDQUFDLElBQUksVUFBVSxDQUFDLElBQUksQ0FBQyxLQUFLLENBQUMsRUFBRSxDQUFDLE9BQU8sS0FBSyxLQUFLLFFBQVEsQ0FBQyxFQUFFLENBQUM7WUFDdEYsTUFBTSxJQUFBLGlDQUFjLEVBQUMsNENBQTRDLENBQUMsQ0FBQztRQUNyRSxDQUFDO0lBQ0gsQ0FBQztJQUVELElBQUksSUFBSSxLQUFLLFNBQVMsRUFBRSxDQUFDO1FBQ3ZCLE1BQU0sS0FBSyxHQUNULEtBQUssQ0FBQyxPQUFPLENBQUMsSUFBSSxDQUFD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

package/dist/data/data-routes-middleware.d.ts

@@ -0,0 +1,12 @@
+import type { AgentDataClient, AgentDataClientOptions } from './agent-data-client';
+import type { Logger } from '../ports/logger-port';
+import type ReadModelStore from '../read-model/read-model-store';
+import type { Middleware } from 'koa';
+export interface DataRoutesMiddlewareOptions {
+    store: ReadModelStore;
+    agentUrl: string;
+    logger: Logger;
+    createClient?: (options: AgentDataClientOptions) => AgentDataClient;
+}
+export default function createDataRoutesMiddleware({ store, agentUrl, logger, createClient, }: DataRoutesMiddlewareOptions): Middleware;
+//# sourceMappingURL=data-routes-middleware.d.ts.map

package/dist/data/data-routes-middleware.js

@@ -0,0 +1,159 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = createDataRoutesMiddleware;
+const agent_data_client_1 = __importDefault(require("./agent-data-client"));
+const agent_query_1 = require("./agent-query");
+const response_mappers_1 = require("./response-mappers");
+const agent_error_mapper_1 = require("../http/agent-error-mapper");
+const bff_http_error_1 = require("../http/bff-http-error");
+const bff_local_errors_1 = require("../http/bff-local-errors");
+const errors_1 = __importDefault(require("../read-model/errors"));
+const relation_field_guard_1 = __importDefault(require("../validation/relation-field-guard"));
+const DATA_ROUTE = /^\/agent\/v1\/([^/]+)\/(list|count)$/;
+const RELATION_ROUTE = /^\/agent\/v1\/([^/]+)\/relations\/([^/]+)\/(list|count)$/;
+// Only to-many relations expose list/count on the agent; to-one relations get update-relation only.
+// A polymorphic relation carrying multiple targets is always the to-one (PolymorphicManyToOne) side.
+function resolveForeignCollection(target) {
+    if (!target || !('target' in target))
+        return null;
+    if (target.type !== 'HasMany' && target.type !== 'BelongsToMany')
+        return null;
+    return target.target;
+}
+function decodeSegment(raw, label) {
+    try {
+        return decodeURIComponent(raw);
+    }
+    catch {
+        throw (0, bff_local_errors_1.invalidRequest)(`Malformed ${label} in path`);
+    }
+}
+async function resolveReadModel(store) {
+    try {
+        return await store.getReadModel();
+    }
+    catch (error) {
+        if (error instanceof errors_1.default)
+            throw (0, bff_local_errors_1.schemaUnavailable)();
+        throw error;
+    }
+}
+// Only the agent call is wrapped: guard, query-building and mapping errors are BFF-origin and must
+// keep their own type, not be recategorized as agent errors.
+async function callAgent(fn, logger) {
+    try {
+        return await fn();
+    }
+    catch (error) {
+        throw (0, agent_error_mapper_1.mapAgentError)(error, { logger });
+    }
+}
+async function handleList(ctx, body, deps) {
+    (0, relation_field_guard_1.default)((0, agent_query_1.collectListFieldPaths)(body));
+    const query = (0, agent_query_1.buildListAgentQuery)(deps.collection, deps.timezone, body);
+    const records = await callAgent(() => deps.client.list(deps.collection, query), deps.logger);
+    ctx.status = 200;
+    ctx.body = (0, response_mappers_1.mapListResponse)(deps.collection, records, deps.primaryKeys);
+}
+async function handleCount(ctx, body, deps) {
+    (0, relation_field_guard_1.default)((0, agent_query_1.collectCountFieldPaths)(body));
+    const query = (0, agent_query_1.buildCountAgentQuery)(deps.timezone, body);
+    const raw = await callAgent(() => deps.client.countRaw(deps.collection, query), deps.logger);
+    ctx.status = 200;
+    ctx.body = (0, response_mappers_1.mapCountResponse)(raw);
+}
+async function handleRelationList(ctx, body, deps) {
+    // The nested-relation guard IS wired here: the agent's list-related asserts browse only on the
+    // immediate foreign collection, so a nested `:`-path would traverse to a third collection whose
+    // browse is never checked. Plain foreign fields (no `:`) are unaffected.
+    (0, relation_field_guard_1.default)((0, agent_query_1.collectListFieldPaths)(body));
+    const query = (0, agent_query_1.buildListAgentQuery)(deps.foreignCollection, deps.timezone, body);
+    const records = await callAgent(() => deps.client.listRelation(deps.collection, body.parentId, deps.relation, query), deps.logger);
+    ctx.status = 200;
+    ctx.body = (0, response_mappers_1.mapListResponse)(deps.foreignCollection, records, deps.primaryKeys);
+}
+async function handleRelationCount(ctx, body, deps) {
+    (0, relation_field_guard_1.default)((0, agent_query_1.collectCountFieldPaths)(body));
+    const query = (0, agent_query_1.buildCountAgentQuery)(deps.timezone, body);
+    const raw = await callAgent(() => deps.client.countRelationRaw(deps.collection, body.parentId, deps.relation, query), deps.logger);
+    ctx.status = 200;
+    ctx.body = (0, response_mappers_1.mapCountResponse)(raw);
+}
+async function handleRelation(ctx, rawBody, match, { deps, readModel }) {
+    const relation = decodeSegment(match[2], 'relation name');
+    const operation = match[3];
+    // The URL identity (does this listable relation exist?) is resolved before the body,
+    // so a bad path 404s before its payload is inspected.
+    const foreignCollection = resolveForeignCollection(readModel.getRelationTarget(deps.collection, relation));
+    // TODO(PRD-672): the read-model's relation map is the allow-list, so an absent/to-one/polymorphic
+    // relation cannot be told from a disallowed one — every non-listable relation maps to 404 here;
+    // `relation_not_allowed` (403) has no local trigger, mirroring `collection_not_allowed`.
+    if (!foreignCollection) {
+        throw (0, bff_local_errors_1.unknownRelation)(`Unknown relation: ${deps.collection}.${relation}`);
+    }
+    // The agent's count-related authorizes only the parent, so an unguarded foreign collection would
+    // leak a hidden collection's rows/count. Guard it here, mirroring the parent allow-list check.
+    if (!readModel.isCollectionAllowed(foreignCollection)) {
+        throw (0, bff_local_errors_1.unknownCollection)();
+    }
+    const relationDeps = { ...deps, relation, foreignCollection };
+    if (operation === 'list') {
+        await handleRelationList(ctx, (0, agent_query_1.parseRelationListRequest)(rawBody), {
+            ...relationDeps,
+            primaryKeys: readModel.getPrimaryKeys(foreignCollection),
+        });
+    }
+    else {
+        await handleRelationCount(ctx, (0, agent_query_1.parseRelationCountRequest)(rawBody), relationDeps);
+    }
+}
+function createDataRoutesMiddleware({ store, agentUrl, logger, createClient = agent_data_client_1.default, }) {
+    return async function dataRoutesMiddleware(ctx, next) {
+        const dataMatch = DATA_ROUTE.exec(ctx.path);
+        const relationMatch = dataMatch ? null : RELATION_ROUTE.exec(ctx.path);
+        const match = dataMatch ?? relationMatch;
+        if (!match || ctx.method !== 'POST') {
+            await next();
+            return;
+        }
+        const collection = decodeSegment(match[1], 'collection name');
+        // The agent token is minted only on the API-key path; the OAuth path sets a principal but no
+        // agent token yet. Fail closed instead of calling the agent with `Bearer undefined`.
+        // TODO(PRD-637): mint an agent token from the OAuth principal so data routes work in OAuth mode.
+        const token = ctx.state.agentToken;
+        if (!token)
+            throw (0, bff_http_error_1.unauthorized)('No agent credentials for this request');
+        const readModel = await resolveReadModel(store);
+        if (!readModel.isCollectionAllowed(collection)) {
+            // TODO(PRD-671): the read-model exposes a single allow-list (the exposed collections), so it
+            // cannot tell an unknown collection from a known-but-disallowed one. Every absent name maps
+            // to 404 here; `collection_not_allowed` (403) has no local trigger until a distinct exposure
+            // source exists. Escalated on the ticket — revisit when Anthony answers.
+            throw (0, bff_local_errors_1.unknownCollection)(`Unknown collection: ${collection}`);
+        }
+        const deps = {
+            collection,
+            client: createClient({ agentUrl, token }),
+            timezone: ctx.state.timezone,
+            logger,
+        };
+        const rawBody = ctx.request.body ?? {};
+        if (relationMatch) {
+            await handleRelation(ctx, rawBody, relationMatch, { deps, readModel });
+            return;
+        }
+        const operation = match[2];
+        if (operation === 'list') {
+            const body = (0, agent_query_1.parseListRequest)(rawBody);
+            await handleList(ctx, body, { ...deps, primaryKeys: readModel.getPrimaryKeys(collection) });
+        }
+        else {
+            const body = (0, agent_query_1.parseCountRequest)(rawBody);
+            await handleCount(ctx, body, deps);
+        }
+    };
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZGF0YS1yb3V0ZXMtbWlkZGxld2FyZS5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9kYXRhL2RhdGEtcm91dGVzLW1pZGRsZXdhcmUudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7Ozs7QUFxTUEsNkNBMkRDO0FBblBELDRFQUErRDtBQUMvRCwrQ0FTdUI7QUFDdkIseURBQXVFO0FBQ3ZFLG1FQUEyRDtBQUMzRCwyREFBc0Q7QUFDdEQsK0RBS2tDO0FBQ2xDLGtFQUEwRDtBQUMxRCw4RkFBNEU7QUFFNUUsTUFBTSxVQUFVLEdBQUcsc0NBQXNDLENBQUM7QUFDMUQsTUFBTSxjQUFjLEdBQUcsMERBQTBELENBQUM7QUFFbEYsb0dBQW9HO0FBQ3BHLHFHQUFxRztBQUNyRyxTQUFTLHdCQUF3QixDQUFDLE1BQWtDO0lBQ2xFLElBQUksQ0FBQyxNQUFNLElBQUksQ0FBQyxDQUFDLFFBQVEsSUFBSSxNQUFNLENBQUM7UUFBRSxPQUFPLElBQUksQ0FBQztJQUNsRCxJQUFJLE1BQU0sQ0FBQyxJQUFJLEtBQUssU0FBUyxJQUFJLE1BQU0sQ0FBQyxJQUFJLEtBQUssZUFBZTtRQUFFLE9BQU8sSUFBSSxDQUFDO0lBRTlFLE9BQU8sTUFBTSxDQUFDLE1BQU0sQ0FBQztBQUN2QixDQUFDO0FBa0JELFNBQVMsYUFBYSxDQUFDLEdBQVcsRUFBRSxLQUFhO0lBQy9DLElBQUksQ0FBQztRQUNILE9BQU8sa0JBQWtCLENBQUMsR0FBRyxDQUFDLENBQUM7SUFDakMsQ0FBQztJQUFDLE1BQU0sQ0FBQztRQUNQLE1BQU0sSUFBQSxpQ0FBYyxFQUFDLGFBQWEsS0FBSyxVQUFVLENBQUMsQ0FBQztJQUNyRCxDQUFDO0FBQ0gsQ0FBQztBQUVELEtBQUssVUFBVSxnQkFBZ0IsQ0FBQyxLQUFxQjtJQUNuRCxJQUFJLENBQUM7UUFDSCxPQUFPLE1BQU0sS0FBSyxDQUFDLFlBQVksRUFBRSxDQUFDO0lBQ3BDLENBQUM7SUFBQyxPQUFPLEtBQUssRUFBRSxDQUFD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

package/dist/data/pack-id.d.ts

@@ -0,0 +1,9 @@
+import type { PrimaryKeyField } from '../read-model/read-model';
+/**
+ * Rebuild the structured primary key of a record from its opaque packed id, mirroring the agent's
+ * `IdUtils.packId`/`unpackId` (`|`-joined values, `Number` columns cast back to numbers). Returns a
+ * `{ pkField: value }` map for `__forest.primaryKey`. Throws a mapping error rather than emitting a
+ * malformed key when the schema lacks key metadata or the packed id shape does not match it.
+ */
+export default function unpackPrimaryKey(packedId: string, primaryKeys: PrimaryKeyField[]): Record<string, string | number>;
+//# sourceMappingURL=pack-id.d.ts.map

package/dist/data/pack-id.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = unpackPrimaryKey;
+const bff_local_errors_1 = require("../http/bff-local-errors");
+const PACKED_ID_SEPARATOR = '|';
+// The only column type unpacked to a number, mirroring the agent's `IdUtils.unpackId`.
+const NUMBER_COLUMN_TYPE = 'Number';
+/**
+ * Rebuild the structured primary key of a record from its opaque packed id, mirroring the agent's
+ * `IdUtils.packId`/`unpackId` (`|`-joined values, `Number` columns cast back to numbers). Returns a
+ * `{ pkField: value }` map for `__forest.primaryKey`. Throws a mapping error rather than emitting a
+ * malformed key when the schema lacks key metadata or the packed id shape does not match it.
+ */
+function unpackPrimaryKey(packedId, primaryKeys) {
+    if (primaryKeys.length === 0) {
+        throw (0, bff_local_errors_1.mappingError)('Cannot build primary key: the collection exposes no key metadata');
+    }
+    const values = packedId.split(PACKED_ID_SEPARATOR);
+    if (values.length !== primaryKeys.length) {
+        throw (0, bff_local_errors_1.mappingError)(`Cannot build primary key: expected ${primaryKeys.length} values, found ${values.length}`);
+    }
+    const result = {};
+    primaryKeys.forEach(({ name, type }, index) => {
+        const value = values[index];
+        if (type !== NUMBER_COLUMN_TYPE) {
+            result[name] = value;
+            return;
+        }
+        const numeric = Number(value);
+        if (Number.isNaN(numeric)) {
+            throw (0, bff_local_errors_1.mappingError)(`Cannot build primary key: invalid numeric value "${value}" for "${name}"`);
+        }
+        result[name] = numeric;
+    });
+    return result;
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGFjay1pZC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uLy4uL3NyYy9kYXRhL3BhY2staWQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7QUFlQSxtQ0F1Q0M7QUFwREQsK0RBQXdEO0FBRXhELE1BQU0sbUJBQW1CLEdBQUcsR0FBRyxDQUFDO0FBRWhDLHVGQUF1RjtBQUN2RixNQUFNLGtCQUFrQixHQUFHLFFBQVEsQ0FBQztBQUVwQzs7Ozs7R0FLRztBQUNILFNBQXdCLGdCQUFnQixDQUN0QyxRQUFnQixFQUNoQixXQUE4QjtJQUU5QixJQUFJLFdBQVcsQ0FBQyxNQUFNLEtBQUssQ0FBQyxFQUFFLENBQUM7UUFDN0IsTUFBTSxJQUFBLCtCQUFZLEVBQUMsa0VBQWtFLENBQUMsQ0FBQztJQUN6RixDQUFDO0lBRUQsTUFBTSxNQUFNLEdBQUcsUUFBUSxDQUFDLEtBQUssQ0FBQyxtQkFBbUIsQ0FBQyxDQUFDO0lBRW5ELElBQUksTUFBTSxDQUFDLE1BQU0sS0FBSyxXQUFXLENBQUMsTUFBTSxFQUFFLENBQUM7UUFDekMsTUFBTSxJQUFBLCtCQUFZLEVBQ2hCLHNDQUFzQyxXQUFXLENBQUMsTUFBTSxrQkFBa0IsTUFBTSxDQUFDLE1BQU0sRUFBRSxDQUMxRixDQUFDO0lBQ0osQ0FBQztJQUVELE1BQU0sTUFBTSxHQUFvQyxFQUFFLENBQUM7SUFFbkQsV0FBVyxDQUFDLE9BQU8sQ0FBQyxDQUFDLEVBQUUsSUFBSSxFQUFFLElBQUksRUFBRSxFQUFFLEtBQUssRUFBRSxFQUFFO1FBQzVDLE1BQU0sS0FBSyxHQUFHLE1BQU0sQ0FBQyxLQUFLLENBQUMsQ0FBQztRQUU1QixJQUFJLElBQUksS0FBSyxrQkFBa0IsRUFBRSxDQUFDO1lBQ2hDLE1BQU0sQ0FBQyxJQUFJLENBQUMsR0FBRyxLQUFLLENBQUM7WUFFckIsT0FBTztRQUNULENBQUM7UUFFRCxNQUFNLE9BQU8sR0FBRyxNQUFNLENBQUMsS0FBSyxDQUFDLENBQUM7UUFFOUIsSUFBSSxNQUFNLENBQUMsS0FBSyxDQUFDLE9BQU8sQ0FBQyxFQUFFLENBQUM7WUFDMUIsTUFBTSxJQUFBLCtCQUFZLEVBQ2hCLG9EQUFvRCxLQUFLLFVBQVUsSUFBSSxHQUFHLENBQzNFLENBQUM7UUFDSixDQUFDO1FBRUQsTUFBTSxDQUFDLElBQUksQ0FBQyxHQUFHLE9BQU8sQ0FBQztJQUN6QixDQUFDLENBQUMsQ0FBQztJQUVILE9BQU8sTUFBTSxDQUFDO0FBQ2hCLENBQUMifQ==