@superpanel-sdk/runtime 0.2.3 → 0.7.0

package/dist/core/slot/schema.js

@@ -1,17 +1,170 @@
-/** Reserved row-identity field name. Authors should not invent another. */
+import { z } from 'zod';
+export const SCALAR_DATA_TYPES = [
+    'string',
+    'text',
+    'phone',
+    'email',
+    'number',
+    'boolean',
+    'date',
+    'datetime',
+    'time',
+    'select',
+    'multi_select',
+];
+/** The types that take `options` (27 §2–§3). */
+export const OPTION_DATA_TYPES = new Set(['select', 'multi_select']);
+const dataTypeSchema = z.enum([...SCALAR_DATA_TYPES, 'contact_schedule']);
+/** Field keys derived fields used; they were removed (13-data-model-v1 §21) and are reported when found. */
+export const REMOVED_DERIVED_KEYS = ['derived', 'dependsOn', 'computeFn'];
+/** A field's `source`, removed (19-page-writable-cells): a page decides what the AI may write. */
+export const REMOVED_SOURCE_KEY = 'source';
+/**
+ * A field's `nullable`, removed: no write ever checked it. Every field starts empty and can be
+ * cleared; a page's `required` says when one must be filled, and the platform keeps a row's id and
+ * parent itself.
+ */
+export const REMOVED_NULLABLE_KEY = 'nullable';
+/**
+ * A field's `enum`, removed (27 §2): a field of a known set of values is a `select` (or `multi_select`)
+ * with `options`.
+ */
+export const REMOVED_ENUM_KEY = 'enum';
+/**
+ * A field's `identifier`, removed: nothing found a contact by it. Who a conversation is with is the
+ * repo's `resolve` to decide; `ctx.api.contact.find` and clearing a contact use `phone` and `email`.
+ */
+export const REMOVED_IDENTIFIER_KEY = 'identifier';
+/** Every row's id: the platform's, on every table; a schema does not write it. */
 export const ROW_ID_FIELD = 'id';
+/**
+ * What every row has besides its fields, the platform's (never a field of a schema): its `id`, when
+ * it was created and when it was last written (ISO 8601). A read can filter and order by them.
+ */
+export const ROW_SYSTEM_KEYS = ['id', 'createdAt', 'updatedAt'];
+/** The row's times: `createdAt`, `updatedAt`. */
+export const ROW_TIME_KEYS = ['createdAt', 'updatedAt'];
+export function isRowTimeKey(key) {
+    return ROW_TIME_KEYS.includes(key);
+}
+/** The definition of every row's `id` (added by the platform to every table and the session). */
 export const idFieldCore = {
-    derived: false,
     label: 'Id',
     dataType: 'string',
-    source: 'system',
     extraction: 'Row identity',
-    enum: null,
-    nullable: false,
-};
-/** Unified row id. Write `id: idField` on every table. */
-export const idField = {
-    ...idFieldCore,
-    identifier: null,
 };
+export const normalFieldCoreSchema = z
+    .object({
+    label: z.string(),
+    dataType: dataTypeSchema,
+    extraction: z.string(),
+    options: z.array(z.string()).optional(),
+})
+    .strict();
+export const tableRefSchema = z
+    .object({
+    table: z.string().min(1),
+    kind: z.enum(['parent', 'lookup']),
+    relatedName: z.string().optional(),
+})
+    .strict();
+export const companyNormalFieldDefSchema = normalFieldCoreSchema
+    .extend({
+    ref: tableRefSchema.optional(),
+    unique: z.literal(true).optional(),
+    deprecated: z.boolean().optional(),
+})
+    .strict();
+const localTime = /^(?:[01]\d|2[0-3]):[0-5]\d$/;
+const localEndTime = /^(?:(?:[01]\d|2[0-3]):[0-5]\d|24:00)$/;
+const localDate = /^\d{4}-\d{2}-\d{2}$/;
+export const localTimeRangeSchema = z
+    .object({ start: z.string().regex(localTime), end: z.string().regex(localEndTime) })
+    .strict()
+    .refine((range) => range.start < range.end, { message: 'start must be before end' });
+export const weekdaySchema = z.enum(['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']);
+function validateWindows(windows, ctx) {
+    for (let index = 1; index < windows.length; index += 1) {
+        const previous = windows[index - 1];
+        const current = windows[index];
+        if (current.start < previous.start) {
+            ctx.addIssue({ code: 'custom', path: [index], message: 'windows must be sorted by start time' });
+        }
+        else if (current.start < previous.end) {
+            ctx.addIssue({ code: 'custom', path: [index], message: 'windows must not overlap' });
+        }
+    }
+}
+const windowsSchema = z.array(localTimeRangeSchema).superRefine(validateWindows);
+const weeklySchema = z
+    .object({
+    mon: windowsSchema,
+    tue: windowsSchema,
+    wed: windowsSchema,
+    thu: windowsSchema,
+    fri: windowsSchema,
+    sat: windowsSchema,
+    sun: windowsSchema,
+})
+    .strict();
+function isValidLocalDate(value) {
+    if (!localDate.test(value))
+        return false;
+    const [year, month, day] = value.split('-').map(Number);
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+export const contactScheduleValueSchema = z
+    .object({
+    weekly: weeklySchema.nullable(),
+    dateOverrides: z.array(z
+        .object({
+        dates: z.array(z.string().refine(isValidLocalDate, 'expected a valid YYYY-MM-DD date')).min(1),
+        windows: windowsSchema,
+    })
+        .strict()),
+})
+    .strict()
+    .superRefine((schedule, ctx) => {
+    const seen = new Set();
+    schedule.dateOverrides.forEach((override, overrideIndex) => {
+        override.dates.forEach((date, dateIndex) => {
+            if (seen.has(date)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: ['dateOverrides', overrideIndex, 'dates', dateIndex],
+                    message: 'each override date may appear only once',
+                });
+            }
+            seen.add(date);
+        });
+    });
+});
+export const companyFieldDefSchema = companyNormalFieldDefSchema;
+export const companyTableDefSchema = z
+    .object({
+    label: z.string(),
+    description: z.string(),
+    fields: z.record(z.string(), companyFieldDefSchema),
+})
+    .strict();
+export const companySchemaSchema = z
+    .record(z.string().min(1), companyTableDefSchema)
+    .refine((schema) => Object.keys(schema).length > 0, {
+    message: 'company schema must define at least one table',
+});
+/** A company with no `schema/session.ts`: sessions have no fields. */
+export const EMPTY_SESSION_SCHEMA = { fields: {} };
+export const sessionFieldDefSchema = normalFieldCoreSchema
+    .extend({
+    dataType: z.enum(SCALAR_DATA_TYPES),
+    deprecated: z.boolean().optional(),
+})
+    .strict();
+export const sessionSchemaSchema = z
+    .object({ fields: z.record(z.string().min(1), sessionFieldDefSchema) })
+    .strict();
+export function isCompanySchema(value) {
+    return companySchemaSchema.safeParse(value).success;
+}
 //# sourceMappingURL=schema.js.map

package/dist/core/slot/types.d.ts

@@ -1,89 +1,52 @@
-import type { DataType } from './schema.js';
-import type { FieldPath } from './path.js';
+import type { ContactSchedule, DataType, TableRef } from './schema.js';
 import type { FieldState } from '../context/types.js';
-export type UpdatedBy = 'slot-filling' | 'derived' | 'function' | 'human' | 'import' | 'platform';
-/** Prior generation archived into FieldValue.history (no reason — 01-slot-db §4.1). */
-export type FieldHistoryEntry = {
-    value: string | number | boolean | null;
-    state: FieldState;
-    at: number;
-    by: UpdatedBy;
-};
-/** In-memory field envelope (01-slot-design §2 + 01-slot-db §4 history). */
+export type UpdatedBy = 'slot-filling' | 'function' | 'human' | 'import' | 'platform';
+/**
+ * In-memory field envelope (01-slot-design §2): the current value only. Earlier values are in the
+ * change log (`SlotWriteLog`, 36 §3).
+ */
 export type FieldValue = {
+    /**
+     * Dialogue evidence quote or write justification (`null` when the writer gave none: plain
+     * function / platform writes, row inserts, imports).
+     * Updating `reason` alone does not count as a C5 state/value change.
+     */
     reason: string | null;
-    value: string | number | boolean | null;
+    /**
+     * Current value; always `null` when `state` is `'empty'` or `'declined'`. `'asked_unknown'` is
+     * `null` unless the field's extraction allows a coarse value; `'filled'` is non-null.
+     */
+    value: SlotValue;
     state: FieldState;
+    /** Epoch milliseconds of the last value/state change. */
     updatedAt: number;
     updatedBy: UpdatedBy;
-    /** Past generations ascending; excludes current. Appended only on C5 change. */
-    history: FieldHistoryEntry[];
-};
-/** One history append produced by a write batch (for platform write_log). */
-export type HistoryAppend = {
-    path: FieldPath;
-    entry: FieldHistoryEntry;
-    /** Set when the write targeted a specific snapshot row. */
-    rowId?: string;
-};
-export type ExtractedField = {
-    reason: string;
-    value: string | number | boolean | null;
-    state: 'filled' | 'asked_unknown' | 'declined';
 };
-export type SingleRowProjection = Record<string, ExtractedField>;
-export type MultiRowProjection = Array<{
-    rowKey: string;
-    fields: Record<string, ExtractedField>;
-}>;
-export type SlotFillingOutput = Record<string, SingleRowProjection | MultiRowProjection>;
-export type RuntimeNormalFieldDef = {
-    derived: false;
+export type SlotValue = string | number | boolean | string[] | ContactSchedule | null;
+export type RuntimeFieldDef = {
     label: string;
+    /** Sequence-specific field meaning shown to slot-filling consumers. */
+    description?: string;
     dataType: DataType;
-    source: 'conversation' | 'system';
     extraction: string;
-    enum: Array<string | number> | null;
-    nullable: boolean;
-    identifier: null | {
-        kind: 'phone' | 'email';
-    };
-    ref: null | {
-        table: string;
-    };
+    /** A `select` / `multi_select` field's choices; null on every other type. */
+    options: string[] | null;
+    ref: null | TableRef;
+    /** No two rows of the table hold the same value (18-record-search-index §4.5). */
+    unique?: true;
     deprecated?: boolean;
 };
-export type RuntimeDerivedFieldDef = {
-    derived: true;
-    label: string;
-    dataType: DataType;
-    dependsOn: FieldPath[];
-    computeFn: string;
-    deprecated?: boolean;
-};
-export type RuntimeFieldDef = RuntimeNormalFieldDef | RuntimeDerivedFieldDef;
 export type RuntimeTableDef = {
     label: string;
-    rows: 'single' | 'multi';
     description: string;
     fields: Record<string, RuntimeFieldDef>;
 };
 /**
- * Compiled schema: one key per table, plus derived graph.
- * `derivedOrder` / `reverseDeps` are reserved and cannot be table names.
+ * Compiled schema: one key per table. Builds compiled before V1.16 also carry `derivedOrder` /
+ * `reverseDeps` (always empty there); those names stay reserved and are skipped when reading.
  */
 export type CompiledSlotSchema = {
-    /** Derived fields in topological order (dependencies first). */
-    derivedOrder: FieldPath[];
-    /** `table.field` → derived fields that list it in dependsOn. */
-    reverseDeps: Record<FieldPath, FieldPath[]>;
-    [table: string]: RuntimeTableDef | FieldPath[] | Record<FieldPath, FieldPath[]>;
-};
-export type SlotCurrent = {
-    contactId: string;
-    caseContactId: string;
-    caseFileId: string;
-    sessionId: string | null;
+    [table: string]: RuntimeTableDef;
 };
 export type SingleRowTableData = {
     id: string;
@@ -95,15 +58,6 @@ export type MultiRowRecord = {
     [field: string]: FieldValue | string;
 };
 export type MultiRowTableData = MultiRowRecord[];
-export type TableData = SingleRowTableData | MultiRowTableData;
-/**
- * Runtime snapshot: `current` plus one key per table.
- * `current` is reserved and cannot be a table name.
- */
-export type RuntimeSlotsSnapshot = {
-    current?: SlotCurrent;
-    [table: string]: TableData | SlotCurrent | undefined;
-};
 export type ValidationIssue = {
     code: string;
     message: string;
@@ -115,32 +69,5 @@ export type ValidationResult = {
     ok: false;
     issues: ValidationIssue[];
 };
-export type WriteSource = Exclude<UpdatedBy, 'derived'>;
-export type ApplyWritesOptions = {
-    source: WriteSource;
-    now?: number;
-    /** When true (default for function/platform), only `source: system` normals. */
-    systemOnly?: boolean;
-};
-export type ApplyWritesResult = {
-    snapshot: RuntimeSlotsSnapshot;
-    changed: FieldPath[];
-    /** Previous generations archived into field envelopes this batch. */
-    history: HistoryAppend[];
-};
-export type RecomputeResult = {
-    snapshot: RuntimeSlotsSnapshot;
-    changed: FieldPath[];
-    history: HistoryAppend[];
-};
-export type SlotFillingValidateResult = {
-    ok: true;
-    accepted: SlotFillingOutput;
-    /** Fields that failed type/enum checks — caller may re-extract. */
-    rejected: FieldPath[];
-} | {
-    ok: false;
-    reason: 'stale-version' | 'invalid-shape';
-    issues: ValidationIssue[];
-};
+export type WriteSource = UpdatedBy;
 //# sourceMappingURL=types.d.ts.map

package/dist/core/slot/value.d.ts

@@ -1,9 +1,34 @@
 import type { DataType } from './schema.js';
-import type { ExtractedField, RuntimeFieldDef, RuntimeNormalFieldDef, ValidationIssue } from './types.js';
+import type { RuntimeFieldDef, ValidationIssue } from './types.js';
+/** date values slot filling must write. Partial precision is the coarse form C3 still accepts. */
+export declare const DATE_VALUE_PATTERN: string;
+export declare const DATE_VALUE_FORMAT = "YYYY, YYYY-MM, or YYYY-MM-DD";
+/** ISO-8601 datetime with a timezone offset or Z. */
+export declare const DATETIME_VALUE_PATTERN: string;
+export declare const DATETIME_VALUE_FORMAT = "ISO-8601 datetime with a timezone offset or Z";
+/** A time of day (27 §4): `HH:mm`, 24-hour, `00:00`–`23:59`. */
+export declare const TIME_VALUE_PATTERN: string;
+export declare const TIME_VALUE_FORMAT = "a time of day HH:mm, 24-hour (15:30)";
+/**
+ * A `phone` value as stored: E.164, any country, with an extension in RFC 3966 form when there is one
+ * (`+14155550123;ext=123`). The write entry converts what it is given first.
+ */
+export declare const PHONE_VALUE_PATTERN: string;
+/** An `email` value as stored: lower-cased (the write entry lower-cases what it is given first). */
+export declare const EMAIL_VALUE_PATTERN: string;
+/** Characters of a string, as Postgres and people count them (a surrogate pair is one). */
+export declare function stringChars(value: string): number;
+/** UTF-8 bytes of a string. */
+export declare function utf8Bytes(value: string): number;
+/** UTF-8 bytes a `string` takes in its indexes: as written, or lower-cased if that is longer. */
+export declare function indexedBytes(value: string): number;
+/** What a value of `dataType` must look like, for messages. */
+export declare function dataTypeFormat(dataType: DataType): string;
 export declare function isValidDataTypeValue(dataType: DataType, value: unknown): boolean;
-export declare function validateExtractedField(field: RuntimeNormalFieldDef, extracted: ExtractedField, path: string): ValidationIssue[];
-/** Validate a bare write value for a normal or derived field. */
+/** Validate a bare write value for a field. */
 export declare function validateBareValue(field: RuntimeFieldDef, value: unknown, path: string, options?: {
     allowNull?: boolean;
 }): ValidationIssue[];
+/** What of a `select` / `multi_select` value is not one of the field's options; empty for any other field. */
+export declare function optionsOutside(field: Pick<RuntimeFieldDef, 'options'>, value: unknown): unknown[];
 //# sourceMappingURL=value.d.ts.map

package/dist/core/slot/value.js

@@ -1,12 +1,79 @@
-const DATE_RE = /^\d{4}(-\d{2}(-\d{2})?)?$/;
-// ISO-8601 datetime with timezone offset or Z
-const DATETIME_RE = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$/;
+import { LIMITS } from './company-metadata.js';
+import { contactScheduleValueSchema } from './schema.js';
+/** date values slot filling must write. Partial precision is the coarse form C3 still accepts. */
+export const DATE_VALUE_PATTERN = String.raw `^\d{4}(-\d{2}(-\d{2})?)?$`;
+export const DATE_VALUE_FORMAT = 'YYYY, YYYY-MM, or YYYY-MM-DD';
+/** ISO-8601 datetime with a timezone offset or Z. */
+export const DATETIME_VALUE_PATTERN = String.raw `^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?(Z|[+-]\d{2}:\d{2})$`;
+export const DATETIME_VALUE_FORMAT = 'ISO-8601 datetime with a timezone offset or Z';
+/** A time of day (27 §4): `HH:mm`, 24-hour, `00:00`–`23:59`. */
+export const TIME_VALUE_PATTERN = String.raw `^(?:[01]\d|2[0-3]):[0-5]\d$`;
+export const TIME_VALUE_FORMAT = 'a time of day HH:mm, 24-hour (15:30)';
+/**
+ * A `phone` value as stored: E.164, any country, with an extension in RFC 3966 form when there is one
+ * (`+14155550123;ext=123`). The write entry converts what it is given first.
+ */
+export const PHONE_VALUE_PATTERN = String.raw `^\+[1-9]\d{6,14}(;ext=\d{1,10})?$`;
+/** An `email` value as stored: lower-cased (the write entry lower-cases what it is given first). */
+export const EMAIL_VALUE_PATTERN = String.raw `^[^\sA-Z@]+@[^\sA-Z@]+\.[^\sA-Z@]+$`;
+const DATE_RE = new RegExp(DATE_VALUE_PATTERN);
+const DATETIME_RE = new RegExp(DATETIME_VALUE_PATTERN);
+const TIME_RE = new RegExp(TIME_VALUE_PATTERN);
+const PHONE_RE = new RegExp(PHONE_VALUE_PATTERN);
+const EMAIL_RE = new RegExp(EMAIL_VALUE_PATTERN);
+const utf8 = new TextEncoder();
+/** Characters of a string, as Postgres and people count them (a surrogate pair is one). */
+export function stringChars(value) {
+    let count = 0;
+    for (const _ of value)
+        count += 1;
+    return count;
+}
+/** UTF-8 bytes of a string. */
+export function utf8Bytes(value) {
+    return utf8.encode(value).length;
+}
+/** UTF-8 bytes a `string` takes in its indexes: as written, or lower-cased if that is longer. */
+export function indexedBytes(value) {
+    return Math.max(utf8Bytes(value), utf8Bytes(value.toLowerCase()));
+}
+/** What a value of `dataType` must look like, for messages. */
+export function dataTypeFormat(dataType) {
+    switch (dataType) {
+        case 'string':
+            return `a string of at most ${LIMITS.stringBytes} bytes (UTF-8; a longer value is a text field)`;
+        case 'text':
+            return `a string of at most ${LIMITS.textBytes} bytes`;
+        case 'phone':
+            return 'a phone number, any country (stored as E.164, e.g. +14155550123; with an extension +14155550123;ext=12)';
+        case 'email':
+            return 'an email address';
+        case 'date':
+            return DATE_VALUE_FORMAT;
+        case 'datetime':
+            return DATETIME_VALUE_FORMAT;
+        case 'time':
+            return TIME_VALUE_FORMAT;
+        case 'select':
+            return 'one of its options';
+        case 'multi_select':
+            return 'a list of its options ([] for none of them)';
+        default:
+            return dataType;
+    }
+}
 export function isValidDataTypeValue(dataType, value) {
     if (value === null)
         return true;
     switch (dataType) {
         case 'string':
-            return typeof value === 'string';
+            return typeof value === 'string' && indexedBytes(value) <= LIMITS.stringBytes;
+        case 'text':
+            return typeof value === 'string' && utf8Bytes(value) <= LIMITS.textBytes;
+        case 'phone':
+            return typeof value === 'string' && PHONE_RE.test(value);
+        case 'email':
+            return typeof value === 'string' && EMAIL_RE.test(value);
         case 'number':
             return typeof value === 'number' && Number.isFinite(value);
         case 'boolean':
@@ -15,61 +82,22 @@ export function isValidDataTypeValue(dataType, value) {
             return typeof value === 'string' && DATE_RE.test(value);
         case 'datetime':
             return typeof value === 'string' && DATETIME_RE.test(value);
+        case 'time':
+            return typeof value === 'string' && TIME_RE.test(value);
+        case 'select':
+            return typeof value === 'string';
+        case 'multi_select':
+            return Array.isArray(value) && value.every((item) => typeof item === 'string');
+        case 'contact_schedule':
+            return contactScheduleValueSchema.safeParse(value).success;
     }
 }
-export function validateExtractedField(field, extracted, path) {
-    const issues = [];
-    if (typeof extracted.reason !== 'string' || extracted.reason.length === 0) {
-        issues.push({
-            code: 'missing-reason',
-            message: 'Extracted field requires a non-empty reason',
-            path,
-        });
-    }
-    if (extracted.state !== 'filled' && extracted.state !== 'asked_unknown' && extracted.state !== 'declined') {
-        issues.push({
-            code: 'invalid-state',
-            message: `Invalid extracted state: ${String(extracted.state)}`,
-            path,
-        });
-        return issues;
-    }
-    if (extracted.state === 'declined' && extracted.value !== null) {
-        issues.push({
-            code: 'declined-non-null',
-            message: 'declined fields must have value null',
-            path,
-        });
-    }
-    if (extracted.state === 'filled' && extracted.value === null && !field.nullable) {
-        issues.push({
-            code: 'filled-null',
-            message: 'filled requires non-null value unless nullable: true',
-            path,
-        });
-    }
-    if (extracted.value !== null && !isValidDataTypeValue(field.dataType, extracted.value)) {
-        issues.push({
-            code: 'type-mismatch',
-            message: `value does not match dataType ${field.dataType}`,
-            path,
-        });
-    }
-    if (extracted.value !== null && field.enum && !field.enum.includes(extracted.value)) {
-        issues.push({
-            code: 'enum-mismatch',
-            message: `value ${String(extracted.value)} not in enum`,
-            path,
-        });
-    }
-    return issues;
-}
-/** Validate a bare write value for a normal or derived field. */
+/** Validate a bare write value for a field. */
 export function validateBareValue(field, value, path, options = {}) {
     const issues = [];
     const allowNull = options.allowNull ?? true;
     if (value === null || value === undefined) {
-        if (!allowNull && !(field.derived === false && field.nullable)) {
+        if (!allowNull) {
             issues.push({
                 code: 'null-not-allowed',
                 message: 'null is not allowed for this field',
@@ -81,17 +109,25 @@ export function validateBareValue(field, value, path, options = {}) {
     if (!isValidDataTypeValue(field.dataType, value)) {
         issues.push({
             code: 'type-mismatch',
-            message: `value does not match dataType ${field.dataType}`,
+            message: `value does not match dataType ${field.dataType}: expected ${dataTypeFormat(field.dataType)}`,
             path,
         });
     }
-    if (!field.derived && field.enum && !field.enum.includes(value)) {
+    const outside = optionsOutside(field, value);
+    if (outside.length > 0) {
         issues.push({
-            code: 'enum-mismatch',
-            message: `value ${String(value)} not in enum`,
+            code: 'not-an-option',
+            message: `${outside.map((v) => JSON.stringify(v)).join(', ')} not one of the options (${field.options.join(', ')})`,
             path,
         });
     }
     return issues;
 }
+/** What of a `select` / `multi_select` value is not one of the field's options; empty for any other field. */
+export function optionsOutside(field, value) {
+    if (!field.options)
+        return [];
+    const items = Array.isArray(value) ? value : [value];
+    return items.filter((item) => !field.options.includes(item));
+}
 //# sourceMappingURL=value.js.map