@hypequery/protocol 0.24.0 → 0.24.2

package/dist/client-contract/errors.d.ts

@@ -15,7 +15,9 @@ export type ProtocolClientContractErrorCode = keyof typeof CLIENT_ERROR_MESSAGES
 export declare class ProtocolClientContractError extends TypeError {
     readonly code: ProtocolClientContractErrorCode;
     readonly path: string;
-    constructor(code: ProtocolClientContractErrorCode, path?: string);
+    /** For `HQ_CLIENT_UNKNOWN_FIELD`, the first member at `path` this version doesn't know. */
+    readonly field?: string;
+    constructor(code: ProtocolClientContractErrorCode, path?: string, field?: string);
 }
-export declare function clientError(code: ProtocolClientContractErrorCode, path?: string): never;
+export declare function clientError(code: ProtocolClientContractErrorCode, path?: string, field?: string): never;
 //# sourceMappingURL=errors.d.ts.map

package/dist/client-contract/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/client-contract/errors.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB;;;;;;;;;;;;EAYhC,CAAC;AACH,MAAM,MAAM,+BAA+B,GAAG,MAAM,OAAO,qBAAqB,CAAC;AACjF,qBAAa,2BAA4B,SAAQ,SAAS;IACxD,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBACV,IAAI,EAAE,+BAA+B,EAAE,IAAI,SAAK;CAM7D;AACD,wBAAgB,WAAW,CAAC,IAAI,EAAE,+BAA+B,EAAE,IAAI,SAAK,GAAG,KAAK,CAEnF"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/client-contract/errors.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB;;;;;;;;;;;;EAYhC,CAAC;AACH,MAAM,MAAM,+BAA+B,GAAG,MAAM,OAAO,qBAAqB,CAAC;AACjF,qBAAa,2BAA4B,SAAQ,SAAS;IACxD,QAAQ,CAAC,IAAI,EAAE,+BAA+B,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;gBACZ,IAAI,EAAE,+BAA+B,EAAE,IAAI,SAAK,EAAE,KAAK,CAAC,EAAE,MAAM;CAO7E;AACD,wBAAgB,WAAW,CAAC,IAAI,EAAE,+BAA+B,EAAE,IAAI,SAAK,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,KAAK,CAEnG"}

package/dist/client-contract/errors.js

@@ -14,13 +14,17 @@ export const CLIENT_ERROR_MESSAGES = Object.freeze({
 export class ProtocolClientContractError extends TypeError {
     code;
     path;
-    constructor(code, path = '') {
+    /** For `HQ_CLIENT_UNKNOWN_FIELD`, the first member at `path` this version doesn't know. */
+    field;
+    constructor(code, path = '', field) {
         super(CLIENT_ERROR_MESSAGES[code]);
         this.name = 'ProtocolClientContractError';
         this.code = code;
         this.path = path;
+        if (field !== undefined)
+            this.field = field;
     }
 }
-export function clientError(code, path = '') {
-    throw new ProtocolClientContractError(code, path);
+export function clientError(code, path = '', field) {
+    throw new ProtocolClientContractError(code, path, field);
 }

package/dist/client-contract/primitives.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/client-contract/primitives.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACnD,eAAO,MAAM,kBAAkB,uDAAwD,CAAC;AACxF,eAAO,MAAM,aAAa,wEAAyE,CAAC;AACpG,eAAO,MAAM,gBAAgB,UAAmG,CAAC;AACjI,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAElE;AACD,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAGjE;AACD,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAKjG;AACD,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAKzF;AACD,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAG/F;AACD,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAG1D;AACD,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKvF;AACD,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,UAAQ,GAAG,MAAM,CAO5E;AACD,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAOzF;AACD,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI1D;AAED,6FAA6F;AAC7F,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAQzD;AACD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7D"}
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../src/client-contract/primitives.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AACnD,eAAO,MAAM,kBAAkB,uDAAwD,CAAC;AACxF,eAAO,MAAM,aAAa,wEAAyE,CAAC;AACpG,eAAO,MAAM,gBAAgB,UAAmG,CAAC;AACjI,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAElE;AACD,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAGjE;AAMD,qFAAqF;AACrF,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAKjG;AACD,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAKzF;AACD,wBAAgB,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAG/F;AACD,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAG1D;AACD,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAKvF;AACD,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,UAAQ,GAAG,MAAM,CAO5E;AACD,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAOzF;AACD,wBAAgB,KAAK,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAI1D;AAED,6FAA6F;AAC7F,wBAAgB,IAAI,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAQzD;AACD,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAG7D"}

package/dist/client-contract/primitives.js

@@ -12,19 +12,23 @@ export function record(input, path) {
         clientError('HQ_CLIENT_SHAPE', path);
     return input;
 }
+/** The error keeps the shared fixtures' parent path and names the first unlisted member as `field`. */
+function rejectUnknownField(value, keys, path) {
+    const unknown = Object.keys(value).find(key => !keys.includes(key));
+    if (unknown !== undefined)
+        clientError('HQ_CLIENT_UNKNOWN_FIELD', path, unknown);
+}
 /** Closed object whose listed members are all optional; at least one is required. */
 export function optionalShape(input, keys, path) {
     const value = record(input, path);
-    if (Object.keys(value).some(key => !keys.includes(key)))
-        clientError('HQ_CLIENT_UNKNOWN_FIELD', path);
+    rejectUnknownField(value, keys, path);
     if (!keys.some(key => Object.hasOwn(value, key)))
         clientError('HQ_CLIENT_SHAPE', path);
     return value;
 }
 export function shape(input, keys, path) {
     const value = record(input, path);
-    if (Object.keys(value).some(key => !keys.includes(key)))
-        clientError('HQ_CLIENT_UNKNOWN_FIELD', path);
+    rejectUnknownField(value, keys, path);
     if (keys.some(key => !Object.hasOwn(value, key)))
         clientError('HQ_CLIENT_SHAPE', path);
     return value;

package/dist/client-contract/query.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/client-contract/query.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAMzD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AA6ED,gGAAgG;AAChG,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,GAAE,MAAM,GAAG,KAAc,GACxF,eAAe,CAmBjB"}
+{"version":3,"file":"query.d.ts","sourceRoot":"","sources":["../../src/client-contract/query.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAMzD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,sBAAsB,CAAC;IAC1C,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACjD,QAAQ,CAAC,gBAAgB,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAoFD,gGAAgG;AAChG,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,GAAE,MAAM,GAAG,KAAc,GACxF,eAAe,CAwBjB"}

package/dist/client-contract/query.js

@@ -3,88 +3,97 @@ import { validateProtocolClientContract } from './validate.js';
 import { record, shape, integer, timezone } from './primitives.js';
 import { freezeClientData, snapshotClientData } from './safe-data.js';
 import { isProtocolNullCheckOperator } from '../expressions/null-checks.js';
-function array(input, maximum) {
+function array(input, maximum, path) {
     if (!Array.isArray(input) || input.length > maximum)
-        clientError('HQ_CLIENT_QUERY');
+        clientError('HQ_CLIENT_QUERY', path);
     return input;
 }
-function strings(input, allowed, maximum) {
-    const values = array(input, maximum);
-    if (values.some(v => typeof v !== 'string' || !allowed.includes(v))
-        || new Set(values).size !== values.length)
-        clientError('HQ_CLIENT_QUERY');
+function strings(input, allowed, maximum, path) {
+    const values = array(input, maximum, path);
+    const seen = new Set();
+    values.forEach((value, index) => {
+        if (typeof value !== 'string' || !allowed.includes(value) || seen.has(value))
+            clientError('HQ_CLIENT_QUERY', `${path}/${index}`);
+        seen.add(value);
+    });
     return values;
 }
-function predicateValue(value, type, operator, maximum) {
+function predicateValue(value, type, operator, maximum, path) {
     const values = operator === 'between' || operator === 'in' || operator === 'notIn'
-        ? array(value, operator === 'between' ? 2 : maximum) : [value];
+        ? array(value, operator === 'between' ? 2 : maximum, path) : [value];
     if (values.length === 0 || (operator === 'between' && values.length !== 2))
-        clientError('HQ_CLIENT_QUERY');
+        clientError('HQ_CLIENT_QUERY', path);
     for (const item of values) {
         if (type === 'number' ? typeof item !== 'number' || !Number.isFinite(item)
             : type === 'boolean' ? typeof item !== 'boolean' : typeof item !== 'string')
-            clientError('HQ_CLIENT_QUERY');
+            clientError('HQ_CLIENT_QUERY', path);
     }
 }
 function bodyFor(endpoint, source, transport) {
     const keys = ['dimensions', 'filters', 'orderBy', 'limit', 'offset', 'includeMeta',
         ...(endpoint.kind === 'dataset' ? ['measures', 'having'] : []),
         ...(endpoint.time ? ['by', ...(endpoint.time.timezone ? ['timezone'] : [])] : [])];
+    // An unknown member is reported at the root: its name is submitted data.
     if (Object.keys(source).some(key => !keys.includes(key)))
         clientError('HQ_CLIENT_QUERY');
     const caps = endpoint.limits;
-    const dimensions = strings(source.dimensions === undefined ? [] : source.dimensions, Object.keys(endpoint.dimensions).filter(key => endpoint.dimensions[key].groupable), caps.maxDimensions);
+    const dimensions = strings(source.dimensions === undefined ? [] : source.dimensions, Object.keys(endpoint.dimensions).filter(key => endpoint.dimensions[key].groupable), caps.maxDimensions, '/dimensions');
     const selectedMeasures = endpoint.kind === 'metric' ? Object.keys(endpoint.measures)
-        : strings(source.measures === undefined ? endpoint.defaultMeasures : source.measures, Object.keys(endpoint.measures), caps.maxMeasures);
+        : strings(source.measures === undefined ? endpoint.defaultMeasures : source.measures, Object.keys(endpoint.measures), caps.maxMeasures, '/measures');
     if (!dimensions.length && !selectedMeasures.length && source.by === undefined)
         clientError('HQ_CLIENT_QUERY');
-    const filters = array(source.filters === undefined ? [] : source.filters, caps.maxPredicates);
-    for (const item of filters) {
+    const filters = array(source.filters === undefined ? [] : source.filters, caps.maxPredicates, '/filters');
+    filters.forEach((item, index) => {
+        const path = `/filters/${index}`;
         // A null check names no value (RFC 0023), so one carrying `value` fails as an unknown member.
-        const nullCheck = isProtocolNullCheckOperator(record(item, '').operator);
-        const filter = shape(item, nullCheck ? ['field', 'operator'] : ['field', 'operator', 'value'], '');
+        const nullCheck = isProtocolNullCheckOperator(record(item, path).operator);
+        const filter = shape(item, nullCheck ? ['field', 'operator'] : ['field', 'operator', 'value'], path);
         if (typeof filter.field !== 'string' || !Object.hasOwn(endpoint.filters, filter.field))
-            clientError('HQ_CLIENT_QUERY');
+            clientError('HQ_CLIENT_QUERY', `${path}/field`);
         const definition = endpoint.filters[filter.field];
         if (typeof filter.operator !== 'string' || !definition.operators.includes(filter.operator))
-            clientError('HQ_CLIENT_QUERY');
+            clientError('HQ_CLIENT_QUERY', `${path}/operator`);
         if (!nullCheck)
-            predicateValue(filter.value, definition.type, filter.operator, caps.maxFilterValues);
-    }
-    const having = array(source.having === undefined ? [] : source.having, caps.maxPredicates - filters.length);
-    for (const item of having) {
-        const condition = shape(item, ['measure', 'operator', 'value'], '');
+            predicateValue(filter.value, definition.type, filter.operator, caps.maxFilterValues, `${path}/value`);
+    });
+    const having = array(source.having === undefined ? [] : source.having, caps.maxPredicates - filters.length, '/having');
+    having.forEach((item, index) => {
+        const path = `/having/${index}`;
+        const condition = shape(item, ['measure', 'operator', 'value'], path);
         if (typeof condition.measure !== 'string' || !selectedMeasures.includes(condition.measure)
-            || !endpoint.measures[condition.measure].having
-            || typeof condition.operator !== 'string'
+            || !endpoint.measures[condition.measure].having)
+            clientError('HQ_CLIENT_QUERY', `${path}/measure`);
+        if (typeof condition.operator !== 'string'
             || !['eq', 'neq', 'gt', 'gte', 'lt', 'lte', 'between', 'in', 'notIn'].includes(condition.operator))
-            clientError('HQ_CLIENT_QUERY');
-        predicateValue(condition.value, 'number', condition.operator, caps.maxFilterValues);
-    }
+            clientError('HQ_CLIENT_QUERY', `${path}/operator`);
+        predicateValue(condition.value, 'number', condition.operator, caps.maxFilterValues, `${path}/value`);
+    });
     if (source.by !== undefined && (typeof source.by !== 'string' || !endpoint.time?.grains.includes(source.by)))
-        clientError('HQ_CLIENT_QUERY');
+        clientError('HQ_CLIENT_QUERY', '/by');
     if (source.timezone !== undefined)
         timezone(source.timezone, '/timezone');
-    const orderBy = array(source.orderBy === undefined ? [] : source.orderBy, caps.maxOrderBy);
+    const orderBy = array(source.orderBy === undefined ? [] : source.orderBy, caps.maxOrderBy, '/orderBy');
     const orderable = [...dimensions.filter(key => endpoint.dimensions[key].orderable),
         ...selectedMeasures, ...(source.by === undefined ? [] : ['period'])];
     const ordered = new Set();
-    for (const item of orderBy) {
-        const order = shape(item, ['field', 'direction'], '');
-        if (typeof order.field !== 'string' || !orderable.includes(order.field) || ordered.has(order.field)
-            || (order.direction !== 'asc' && order.direction !== 'desc'))
-            clientError('HQ_CLIENT_QUERY');
+    orderBy.forEach((item, index) => {
+        const path = `/orderBy/${index}`;
+        const order = shape(item, ['field', 'direction'], path);
+        if (typeof order.field !== 'string' || !orderable.includes(order.field) || ordered.has(order.field))
+            clientError('HQ_CLIENT_QUERY', `${path}/field`);
+        if (order.direction !== 'asc' && order.direction !== 'desc')
+            clientError('HQ_CLIENT_QUERY', `${path}/direction`);
         ordered.add(order.field);
-    }
+    });
     // HTTP clamps a larger limit; an agent is refused one, so it never reads a
     // silently shortened page as the whole answer.
     const effectiveLimit = Math.min(source.limit === undefined ? caps.defaultLimit
         : integer(source.limit, 1, transport === 'mcp' ? caps.maxLimit : Number.MAX_SAFE_INTEGER, '/limit'), caps.maxLimit);
     const offset = source.offset === undefined ? 0 : integer(source.offset, 0, caps.maxOffset, '/offset');
     if (source.includeMeta !== undefined && typeof source.includeMeta !== 'boolean')
-        clientError('HQ_CLIENT_QUERY');
+        clientError('HQ_CLIENT_QUERY', '/includeMeta');
     if (source.includeMeta === true && !endpoint.metadata)
-        clientError('HQ_CLIENT_QUERY');
+        clientError('HQ_CLIENT_QUERY', '/includeMeta');
     const body = { dimensions, filters, orderBy, limit: effectiveLimit, offset,
         includeMeta: source.includeMeta ?? false,
         ...(endpoint.kind === 'dataset' ? { measures: selectedMeasures, having } : {}),
@@ -118,8 +127,12 @@ export function validateProtocolClientQuery(contract, endpointId, input, transpo
         return bodyFor(endpoint, source, transport);
     }
     catch (error) {
-        if (error instanceof ProtocolClientContractError)
-            clientError('HQ_CLIENT_QUERY', error.path);
+        if (error instanceof ProtocolClientContractError) {
+            // An agent names the time grain `grain`; point at the member it sent.
+            const path = transport === 'mcp' && (error.path === '/by' || error.path.startsWith('/by/'))
+                ? `/grain${error.path.slice(3)}` : error.path;
+            clientError('HQ_CLIENT_QUERY', path);
+        }
         throw error;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypequery/protocol",
-  "version": "0.24.0",
+  "version": "0.24.2",
   "description": "Portable analytics contracts and TypeScript reference implementation for Hypequery",
   "keywords": [
     "hypequery",