@descix/platform-api 2.1.3 → 4.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@descix/platform-api",
3
- "version": "2.1.3",
3
+ "version": "4.0.0",
4
4
  "description": "Shared platform infrastructure: Firestore models, auth/session, permissions, entitlements, email",
5
5
  "repository": {
6
6
  "type": "git",
@@ -40,7 +40,7 @@
40
40
  "node": ">=24.0.0"
41
41
  },
42
42
  "dependencies": {
43
- "@descix/cloud-core": "^1.1.0",
43
+ "@descix/cloud-core": "^2.0.0",
44
44
  "google-auth-library": "^10.5.0",
45
45
  "googleapis": "^169.0.0"
46
46
  }
@@ -68,9 +68,14 @@ export function isValidEmail(email) {
68
68
  * @param {string} subject - Email subject
69
69
  * @param {string} body - Email body (plain text)
70
70
  * @param {string} [fromEmail] - Optional sender email (defaults to DESCIX_ROUTER_COMMUNITY_MANAGER)
71
+ * @param {Object} [options]
72
+ * @param {string} [options.html] - Optional HTML body (Q15, CEO word Unkamon c7bbc15). When
73
+ * present the message is multipart/alternative: the plain `body` is the text part, `html`
74
+ * the html part (last = preferred). Absent, the message is the same single-part text/plain
75
+ * it has always been — no existing caller changes.
71
76
  * @returns {Promise<void>}
72
77
  */
73
- export async function sendEmail(toEmail, subject, body, fromEmail = null) {
78
+ export async function sendEmail(toEmail, subject, body, fromEmail = null, { html = null } = {}) {
74
79
  const utils = getCloudConfig();
75
80
 
76
81
  // The sender/impersonated user - must be a real user in the domain with Gmail access
@@ -98,16 +103,41 @@ export async function sendEmail(toEmail, subject, body, fromEmail = null) {
98
103
 
99
104
  const gmail = google.gmail({ version: 'v1', auth });
100
105
 
101
- // Build the email message with Reply-To header
102
- const message = [
106
+ // Build the email message with Reply-To header. With `html`, multipart/alternative
107
+ // (text part first, html part last — the alternative order of preference); without it,
108
+ // the single-part text/plain message unchanged.
109
+ const headers = [
103
110
  `From: DeSciX <${impersonatedUser}>`,
104
111
  `To: ${toEmail}`,
105
112
  `Reply-To: ${replyToEmail}`,
106
113
  `Subject: ${subject}`,
107
- 'Content-Type: text/plain; charset="UTF-8"',
108
- '',
109
- body
110
- ].join('\n');
114
+ ];
115
+ let message;
116
+ if (html) {
117
+ const boundary = `descix-alt-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`;
118
+ message = [
119
+ ...headers,
120
+ 'MIME-Version: 1.0',
121
+ `Content-Type: multipart/alternative; boundary="${boundary}"`,
122
+ '',
123
+ `--${boundary}`,
124
+ 'Content-Type: text/plain; charset="UTF-8"',
125
+ '',
126
+ body,
127
+ `--${boundary}`,
128
+ 'Content-Type: text/html; charset="UTF-8"',
129
+ '',
130
+ html,
131
+ `--${boundary}--`
132
+ ].join('\n');
133
+ } else {
134
+ message = [
135
+ ...headers,
136
+ 'Content-Type: text/plain; charset="UTF-8"',
137
+ '',
138
+ body
139
+ ].join('\n');
140
+ }
111
141
 
112
142
  const raw = base64UrlEncode(message);
113
143
 
@@ -148,7 +148,7 @@ export const SETTLEMENT_PROFILES = Object.freeze({
148
148
  // public); the command is self-contained and runs from any directory, so it
149
149
  // carries no repo/cwd root.
150
150
  id: 'egpt_tests',
151
- cmd: 'npx -y -p @descix/egpt-math-sdk@0.3.1 egpt-math-bench --quiet',
151
+ cmd: 'npx -y -p @descix/egpt-math-sdk@0.3.2 egpt-math-bench --quiet',
152
152
  expected_when_green: 'Exit 0, ending "EGPT-MATH BENCH: 157 canonical assertions | 157 runnable | 157/157 pass | 0 structurally-gapped (pinned) → RESULT: PASS", preceded by the "wasm sha256 …" provenance line and the "… WASM calls …" counter line — the integer-only (IOP, not FLOP) EGPT math, compiled Rust→WASM; a corrupted WASM exits 1 (no JS fallback ships).',
153
153
  }),
154
154
  Object.freeze({
@@ -100,9 +100,13 @@ export const MODEL_THINKING_CHAIN =
100
100
  'PRECEDENCE — the model and the thinking setting are ONE pair and always come from the SAME '
101
101
  + 'tier; the first tier that states a model supplies both: (1) intelligence_level named on THIS '
102
102
  + 'request, (2) the KB model override, (3) the app default model, (4) the platform default — the '
103
- + "KB's own intelligence_level, else the platform default level, else the platform default model. "
104
- + 'A tier that states a model but no thinking setting sends NO thinking directive and the '
105
- + 'provider decides; a thinking setting is never inherited onto a model it was not declared with.';
103
+ + "KB's own intelligence_level, else the platform default level (there is no separate default model: "
104
+ + 'every level names its model). '
105
+ + 'A tier that states a model but no thinking_level sends NO thinking directive and the '
106
+ + 'provider decides; a thinking_level is never inherited onto a model it was not declared with.';
107
+
108
+ /** The ONE owner of the thinking_level vocabulary on the request surface (per-model support is the server's). */
109
+ export const THINKING_LEVELS = Object.freeze(['minimal', 'low', 'medium', 'high']);
106
110
 
107
111
  export const NATIVE_MCP_TOOLS = Object.freeze([
108
112
  {
@@ -160,8 +164,8 @@ export const NATIVE_MCP_TOOLS = Object.freeze([
160
164
  // the generation knobs; communityManagement.js prepare_chat_context reads the
161
165
  // document-scoping ones). Declared so strict validation admits them.
162
166
  intelligence_level: { type: 'number', description: 'Intelligence level 1-5. A level selects a (model, thinking) PAIR, not just a model tier — higher levels cost more AI credits. ' + MODEL_THINKING_CHAIN },
163
- model: { type: 'string', description: 'Explicit model name. It overrides the whole chain below, and because you changed the model it carries NO inherited thinking setting — pass thinking_budget too if this model needs one. Prefer intelligence_level unless you need one specific model. ' + MODEL_THINKING_CHAIN },
164
- thinking_budget: { type: 'number', description: 'Thinking-token budget for THIS call: -1 dynamic, 0 off, N a fixed cap. The number is mapped onto the provider\'s thinking LEVEL, and which levels exist is a property of the MODEL: on a model whose vocabulary is {high, low} (measured: gemini-2.5-flash, gemini-2.5-pro) there is no "off", so 0 is REFUSED naming the model and its allowed values rather than sent onward. Thinking is also spent from max_output_tokens, so a cap too small to fit it is refused too. It is the request tier\'s thinking statement and wins over whatever the chain resolved. Omit to take the thinking setting from the same tier that supplied the model. ' + MODEL_THINKING_CHAIN },
167
+ model: { type: 'string', description: 'Explicit model name. It overrides the whole chain below, and because you changed the model it carries NO inherited thinking setting — pass thinking_level too if you want one. Prefer intelligence_level unless you need one specific model. ' + MODEL_THINKING_CHAIN },
168
+ thinking_level: { type: 'string', enum: [...THINKING_LEVELS], 'x-enforceEnum': true, description: 'How much the model thinks before answering, for THIS call: minimal, low, medium or high. This is the only thinking control. Which levels exist is a property of the resolved MODEL, and the server REFUSES, by name, a level the resolved model does not support rather than sending it onward. Thinking is also spent from max_output_tokens, so a cap too small to fit it is refused too. It is the request tier\'s thinking statement and wins over whatever the chain resolved. Omit to take the thinking level from the same tier that supplied the model. ' + MODEL_THINKING_CHAIN },
165
169
  temperature: { type: 'number', description: 'Generation temperature override. Omit to inherit the KB/platform default.' },
166
170
  max_output_tokens: { type: 'number', description: 'Cap on generated tokens for this call. Omit to inherit the KB/platform default.' },
167
171
  streaming: { type: 'boolean', description: 'Stream the reply instead of returning it whole. Leave unset/false over MCP tools/call, which returns a single result — this exists for the streaming transports (PWA/Discord).' },
@@ -179,6 +183,13 @@ export const NATIVE_MCP_TOOLS = Object.freeze([
179
183
  workstream_id: { type: 'string', description: "The workstream this question belongs to. When present, the answer runs on a thread OWNED BY THAT WORKSTREAM rather than by the calling user: the server derives the thread owner as roomThreadKey({surface:'workstream', room_id:workstream_id, app_id}) - e.g. 'unk-beast:workstream-ws-c3-librarian' - and stores continuity server-side in the InteractionRooms collection. Send the SAME workstream_id every turn and omit previous_interaction_id; the response's interaction_id is an ECHO for observability, not a handle to resend. A workstream thread is SHARED BY DESIGN: every caller naming the same workstream on the same app continues the same conversation. It is NOT a private per-user conversation and carries no per-user privacy property. A client-supplied interaction_owner_id remains stripped at the door and is not a substitute for this param." },
180
184
  },
181
185
  required: ['app_id', 'user_input'],
186
+ 'x-removedParams': {
187
+ thinking_budget: {
188
+ code: 'THINKING_BUDGET_REMOVED',
189
+ replacement: 'thinking_level',
190
+ message: `thinking_budget no longer exists; use thinking_level, one of ${THINKING_LEVELS.join(', ')}.`,
191
+ },
192
+ },
182
193
  },
183
194
  },
184
195
  {
@@ -459,6 +459,25 @@ export function validateParamsAgainstSchema(schema, params, opts = {}) {
459
459
 
460
460
  const validNames = Object.keys(properties);
461
461
  const supplied = params && typeof params === 'object' ? params : {};
462
+
463
+ // REMOVED PARAMETERS. A schema retires a parameter by listing it under `x-removedParams`
464
+ // ({ name: { code, replacement, message } }). A caller still sending it gets that code and a
465
+ // message naming the replacement, instead of the generic unknown-parameter refusal (which
466
+ // would only guess a spelling). Declared properties win: a name cannot be both.
467
+ const removed = schema['x-removedParams'] && typeof schema['x-removedParams'] === 'object'
468
+ ? schema['x-removedParams'] : {};
469
+ const suppliedKeys = Object.keys(params && typeof params === 'object' ? params : {});
470
+ const removedHit = suppliedKeys.find(k => !(k in properties) && Object.prototype.hasOwnProperty.call(removed, k));
471
+ if (removedHit) {
472
+ const r = removed[removedHit];
473
+ const err = new Error(
474
+ `${commandName}: parameter '${removedHit}' was REMOVED. ${r.message} ` +
475
+ `Rejected at the ${surface} boundary — the parameter was NOT applied, and no default was substituted.`
476
+ );
477
+ err.code = r.code;
478
+ err.data = { command: commandName, removed_parameter: removedHit, replacement: r.replacement, accepted_parameters: validNames };
479
+ throw err;
480
+ }
462
481
  const unknown = Object.keys(supplied).filter(k => !(k in properties) && !isWaived(k));
463
482
  if (unknown.length > 0) {
464
483
  // A refused key that the PLATFORM injects is a different mistake from a typo, and saying so
@@ -534,6 +553,32 @@ export function validateParamsAgainstSchema(schema, params, opts = {}) {
534
553
  err.data = { command: commandName, mistyped_parameters: mistyped, accepted_parameters: validNames };
535
554
  throw err;
536
555
  }
556
+
557
+ // FOURTH GATE: a property that opts in with `x-enforceEnum: true` has its declared `enum`
558
+ // enforced as part of the published contract: a scalar outside it is refused naming the allowed
559
+ // values. Opt-in because most existing enums were advertising-only and their handlers tolerate
560
+ // other values; widening this to every enum is a separate, deliberate decision.
561
+ // Top-level scalars only, like the type gate.
562
+ const outOfEnum = [];
563
+ for (const name of validNames) {
564
+ const value = supplied[name];
565
+ const allowed = properties[name] && properties[name].enum;
566
+ if (isAbsent(value) || !Array.isArray(allowed) || Array.isArray(value)) continue;
567
+ if (properties[name]['x-enforceEnum'] !== true) continue;
568
+ if (!allowed.includes(value)) outOfEnum.push({ parameter: name, allowed, received_shape: describeShape(value) });
569
+ }
570
+ if (outOfEnum.length > 0) {
571
+ const details = outOfEnum.map(m =>
572
+ `'${m.parameter}' must be one of ${m.allowed.join(', ')} but received a value outside that set (${m.received_shape})`
573
+ );
574
+ const err = new Error(
575
+ `${commandName}: invalid parameter value${outOfEnum.length > 1 ? 's' : ''} — ${details.join('; ')}. ` +
576
+ `Rejected at the ${surface} boundary — the value was NOT coerced and the command did NOT run.`
577
+ );
578
+ err.code = 'INVALID_PARAMS';
579
+ err.data = { command: commandName, out_of_enum_parameters: outOfEnum, accepted_parameters: validNames };
580
+ throw err;
581
+ }
537
582
  }
538
583
 
539
584
  /**
@@ -335,7 +335,7 @@ export class App {
335
335
  this.create_date = create_date instanceof Date ? create_date : new Date(create_date);
336
336
  this.owner_id = String(owner_id);
337
337
  // default_app_model: keep as null/absent unless the caller passed an explicit value.
338
- // This avoids re-populating the doc with utils.DEFAULT_AI_MODEL on every hydration,
338
+ // This avoids re-populating the doc with a model on every hydration,
339
339
  // which would shadow the per-level platform default at request time.
340
340
  this.default_app_model = default_app_model || null;
341
341
  this.default_prompt = utils.DEFAULT_COMMUNITY_PROMPT;