@itsoltech/basal-client 0.0.0-stage → 0.1.0

package/dist/esm/questions.js

@@ -0,0 +1,164 @@
+function text(value, name) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new TypeError(`${name} must be a nonempty string`);
+    return value;
+}
+function criteria(values, min, max = Infinity) {
+    if (!values || typeof values !== 'object' || Array.isArray(values))
+        throw new TypeError('criteria must be an object');
+    const entries = Object.entries(values);
+    if (entries.length < min || entries.length > max)
+        throw new TypeError('invalid number of criteria');
+    for (const [key, value] of entries) {
+        text(key, 'criterion key');
+        text(value, 'criterion description');
+    }
+    return Object.fromEntries(entries);
+}
+function number(value, name, probability = false) {
+    if (typeof value !== 'number' || !Number.isFinite(value) || (probability && (value < 0 || value > 1))) {
+        throw new TypeError(`invalid ${name}`);
+    }
+    return value;
+}
+function evidence(options) {
+    if (options.evidence !== undefined && typeof options.evidence !== 'boolean')
+        throw new TypeError('evidence must be boolean');
+    return options.evidence ? { evidence: true } : {};
+}
+/** Immutable snapshot of a typed question. Use factories or the concrete constructors. */
+export class QuestionSpec {
+    wire;
+    constructor(kind, instructions, fields) {
+        this.wire = structuredClone({ ...fields, type: kind, instructions: text(instructions, 'instructions') });
+    }
+    toJSON() { return structuredClone(this.wire); }
+    /** Validate and retrieve an answer with this question's result type. */
+    read(response, id) {
+        const answer = response.answers?.[id];
+        if (!answer || answer.type !== this.wire.type || !answer.probabilities || typeof answer.probabilities !== 'object' || Array.isArray(answer.probabilities)) {
+            throw new TypeError('Basal returned a missing or mismatched answer');
+        }
+        const fields = {
+            choice: { choice: 'string', confidence: 'number' }, noul: { noul: 'number', confidence: 'number' },
+            score: { score: 'number', legend: 'object', confidence: 'number' },
+            multi: { selected: 'object', threshold: 'number', set_confidence: 'number' },
+            act: { action: 'string', answer: 'string', expected_costs: 'object', confidence: 'number', calibration: 'string' },
+        };
+        const data = answer;
+        for (const [field, kind] of Object.entries(fields[answer.type])) {
+            if (typeof data[field] !== kind || data[field] === null || (kind === 'number' && !Number.isFinite(data[field]))) {
+                throw new TypeError('Basal returned an invalid answer field');
+            }
+        }
+        for (const value of Object.values(answer.probabilities))
+            number(value, 'probability', true);
+        const expectedKeys = this.wire.type === 'noul' || (this.wire.type === 'act' && this.wire.criteria === undefined)
+            ? ['true', 'false'] : Array.isArray(this.wire.criteria)
+            ? this.wire.criteria.map((_, index) => String(index)) : Object.keys(this.wire.criteria ?? {});
+        if (expectedKeys.some(key => !Object.hasOwn(answer.probabilities, key)))
+            throw new TypeError('missing outcome probability');
+        if (answer.evidence !== undefined) {
+            if (!Array.isArray(answer.evidence))
+                throw new TypeError('invalid evidence');
+            for (const span of answer.evidence) {
+                if (!span || typeof span.text !== 'string' || !Number.isSafeInteger(span.start) || !Number.isSafeInteger(span.end)
+                    || span.start < 0 || span.end < 0)
+                    throw new TypeError('invalid evidence span');
+                number(span.probability, 'evidence probability', true);
+            }
+        }
+        if (answer.type === 'choice' && !Object.hasOwn(this.wire.criteria ?? {}, answer.choice))
+            throw new TypeError('unknown choice');
+        if (answer.type === 'multi' && (!Array.isArray(answer.selected) || answer.selected.some(k => typeof k !== 'string' || !Object.hasOwn(this.wire.criteria ?? {}, k))))
+            throw new TypeError('invalid selected labels');
+        if (answer.type === 'score' && (Array.isArray(answer.legend) || Object.values(answer.legend).some(v => typeof v !== 'string')))
+            throw new TypeError('invalid legend');
+        if (answer.type === 'act') {
+            if (!['validated', 'unvalidated'].includes(answer.calibration) || !Object.hasOwn(this.wire.costs ?? {}, answer.action) || !expectedKeys.includes(answer.answer))
+                throw new TypeError('invalid action');
+            if (Array.isArray(answer.expected_costs) || Object.keys(this.wire.costs ?? {}).some(key => !Object.hasOwn(answer.expected_costs, key)))
+                throw new TypeError('invalid expected costs');
+            for (const value of Object.values(answer.expected_costs))
+                number(value, 'expected cost');
+        }
+        return { ...answer, ...(answer.type === 'multi' ? {} : { evidence: answer.evidence ?? [] }) };
+    }
+}
+export class ChoiceQuestion extends QuestionSpec {
+    constructor(instructions, values, options = {}) {
+        if (options.option_keys !== undefined && !['show', 'hide'].includes(options.option_keys))
+            throw new TypeError('invalid option_keys');
+        super('choice', instructions, { criteria: criteria(values, 2, 10), ...evidence(options), ...(options.option_keys === 'hide' ? { option_keys: 'hide' } : {}) });
+    }
+}
+export class NoulQuestion extends QuestionSpec {
+    constructor(instructions, options = {}) { super('noul', instructions, evidence(options)); }
+}
+export class ScoreQuestion extends QuestionSpec {
+    constructor(instructions, levels, options = {}) {
+        if (!Array.isArray(levels) || levels.length < 2 || levels.length > 10)
+            throw new TypeError('score requires 2–10 ordered levels');
+        super('score', instructions, { criteria: levels.map(v => text(v, 'level')), ...evidence(options) });
+    }
+}
+export class MultiQuestion extends QuestionSpec {
+    constructor(instructions, values, options = {}) {
+        if ('evidence' in options)
+            throw new TypeError('multi does not support evidence');
+        const fields = { criteria: criteria(values, 1) };
+        if (options.threshold !== undefined)
+            fields.threshold = number(options.threshold, 'threshold', true);
+        for (const key of ['min', 'max']) {
+            const value = options[key];
+            if (value !== undefined) {
+                if (!Number.isInteger(value) || value < 0 || value > Object.keys(values).length)
+                    throw new TypeError(`invalid ${key}`);
+                fields[key] = value;
+            }
+        }
+        if (options.min !== undefined && options.max !== undefined && options.min > options.max)
+            throw new TypeError('min exceeds max');
+        super('multi', instructions, fields);
+    }
+}
+export class ActQuestion extends QuestionSpec {
+    constructor(instructions, costs, options = {}) {
+        const optionsMap = options.criteria === undefined ? undefined : criteria(options.criteria, 2, 10);
+        const outcomes = Object.keys(optionsMap ?? { 'true': 'Yes', 'false': 'No' });
+        if (!costs || typeof costs !== 'object' || Array.isArray(costs) || !Object.keys(costs).length)
+            throw new TypeError('act requires a cost matrix');
+        const matrix = {};
+        for (const [action, row] of Object.entries(costs)) {
+            text(action, 'action');
+            if (!row || typeof row !== 'object' || Array.isArray(row) || Object.keys(row).length !== outcomes.length || outcomes.some(k => !Object.hasOwn(row, k)))
+                throw new TypeError('each cost row must cover every outcome exactly');
+            Object.defineProperty(matrix, action, { value: Object.fromEntries(Object.entries(row).map(([k, v]) => [k, number(v, 'cost')])), enumerable: true });
+        }
+        if (options.defer_action !== undefined && !Object.hasOwn(matrix, options.defer_action))
+            throw new TypeError('unknown defer_action');
+        super('act', instructions, { costs: matrix, ...evidence(options), ...(optionsMap ? { criteria: optionsMap } : {}),
+            ...(options.defer_action === undefined ? {} : { defer_action: options.defer_action }),
+            ...(options.max_error === undefined ? {} : { max_error: number(options.max_error, 'max_error', true) }) });
+    }
+}
+export function choice(instructions, values, options) { return new ChoiceQuestion(instructions, values, options); }
+export function noul(instructions, options) { return new NoulQuestion(instructions, options); }
+export function score(instructions, levels, options) { return new ScoreQuestion(instructions, levels, options); }
+export function multi(instructions, values, options) { return new MultiQuestion(instructions, values, options); }
+export function act(instructions, costs, options) { return new ActQuestion(instructions, costs, options); }
+export function buildRequest(state, questions, options) {
+    if (state === null || state === undefined)
+        throw new TypeError('state must not be null/undefined');
+    if (!questions || !Object.keys(questions).length)
+        throw new TypeError('questions must not be empty');
+    if (Object.getOwnPropertySymbols(questions).length)
+        throw new TypeError('question keys must be strings or numbers');
+    const entries = Object.entries(questions).map(([id, q]) => { text(id, 'question ID'); if (!(q instanceof QuestionSpec))
+        throw new TypeError('expected typed question'); return [id, q.toJSON()]; });
+    if (options.model !== undefined)
+        text(options.model, 'model');
+    if (options.facts !== undefined && !['off', 'auto'].includes(options.facts))
+        throw new TypeError('invalid facts');
+    return { state, questions: Object.fromEntries(entries), ...(options.model === undefined ? {} : { model: options.model }), ...(options.facts === undefined ? {} : { facts: options.facts }) };
+}

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "@itsoltech/basal-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "TypeScript and JavaScript client for the native Basal HTTP API",
+  "type": "module",
+  "main": "./dist/cjs/index.cjs",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.cts",
+        "default": "./dist/cjs/index.cjs"
+      }
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/itsoltech/basal-rs.git",
+    "directory": "sdk/typescript"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node build.mjs",
+    "prepack": "npm run build"
+  },
+  "devDependencies": {
+    "typescript": "6.0.3"
+  }
+}