@superpanel-sdk/runtime 0.2.2 → 0.5.0

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

@@ -1,102 +1,435 @@
-import type { FuncRef } from '../functions/func-ref.js';
-import type { FieldPath } from './path.js';
-export type DataType = 'string' | 'number' | 'boolean' | 'date' | 'datetime';
-/** Shared core for normal (non-derived) fields — company + session. */
+import { z } from 'zod';
+/**
+ * A field's type (18-record-search-index §4.2): `string` is a short value (at most 255 characters,
+ * `LIMITS.stringChars`), `text` a long one (notes, descriptions; not indexed); `phone` is stored in
+ * E.164 and `email` lower-cased, both checked on write. `select` is one of the field's `options`,
+ * `multi_select` a list of them, `time` a time of day `HH:mm` (27-field-types-and-history).
+ */
+export type ScalarDataType = 'string' | 'text' | 'phone' | 'email' | 'number' | 'boolean' | 'date' | 'datetime' | 'time' | 'select' | 'multi_select';
+export type DataType = ScalarDataType | 'contact_schedule';
+export declare const SCALAR_DATA_TYPES: readonly ["string", "text", "phone", "email", "number", "boolean", "date", "datetime", "time", "select", "multi_select"];
+/** The types that take `options` (27 §2–§3). */
+export declare const OPTION_DATA_TYPES: ReadonlySet<DataType>;
+/** Time window within a local day (`HH:mm`; only `end` may be `'24:00'`; `start < end`). */
+export type LocalTimeRange = {
+    start: string;
+    end: string;
+};
+export type ContactWeekday = 'mon' | 'tue' | 'wed' | 'thu' | 'fri' | 'sat' | 'sun';
+/**
+ * A contact's allowed-contact schedule (`contact.contact_schedule`), in their local timezone.
+ * - `weekly`: recurring allowed windows for all seven weekdays (`[]` on a weekday means no contact that day); `null` means no weekly restriction (all day, still clipped to the platform window).
+ * - `dateOverrides`: specific calendar dates (`YYYY-MM-DD`, each at most once) whose `windows` completely replace `weekly` on those dates (`windows: []` means no contact on those dates).
+ * Every window list is sorted by `start` and non-overlapping.
+ */
+export type ContactSchedule = {
+    weekly: Record<ContactWeekday, LocalTimeRange[]> | null;
+    dateOverrides: Array<{
+        dates: string[];
+        windows: LocalTimeRange[];
+    }>;
+};
+/**
+ * Shared core for fields — company + session. Who may write a field is not the schema's to say: the
+ * AI writes only the cells a page opens with `field(...)` (19-page-writable-cells).
+ */
 export type NormalFieldCore = {
-    derived: false;
     label: string;
     dataType: DataType;
-    source: 'conversation' | 'system';
+    /** How to fill this field (on a cell the page opens), or what it means (on one it shows read-only). */
     extraction: string;
-    enum: Array<string | number> | null;
-    nullable: boolean;
+    /** A `select` / `multi_select` field's choices: short codes, their meaning in `extraction` (27 §2). */
+    options?: string[];
 };
-/** Reserved row-identity field name. Authors should not invent another. */
+/** Field keys derived fields used; they were removed (13-data-model-v1 §21) and are reported when found. */
+export declare const REMOVED_DERIVED_KEYS: readonly ['derived', 'dependsOn', 'computeFn'];
+/** A field's `source`, removed (19-page-writable-cells): a page decides what the AI may write. */
+export declare 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 declare 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 declare 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 declare const REMOVED_IDENTIFIER_KEY = "identifier";
+/** Every row's id: the platform's, on every table; a schema does not write it. */
 export declare 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 declare const ROW_SYSTEM_KEYS: readonly ['id', 'createdAt', 'updatedAt'];
+export type RowSystemKey = (typeof ROW_SYSTEM_KEYS)[number];
+/** The row's times: `createdAt`, `updatedAt`. */
+export declare const ROW_TIME_KEYS: readonly ['createdAt', 'updatedAt'];
+export type RowTimeKey = (typeof ROW_TIME_KEYS)[number];
+export declare function isRowTimeKey(key: string): key is RowTimeKey;
+/** The definition of every row's `id` (added by the platform to every table and the session). */
 export declare const idFieldCore: {
-    readonly derived: false;
     readonly label: 'Id';
     readonly dataType: 'string';
-    readonly source: 'system';
     readonly extraction: 'Row identity';
-    readonly enum: null;
-    readonly nullable: false;
 };
-/** Unified row id. Write `id: idField` on every table. */
-export declare const idField: {
-    readonly derived: false;
-    readonly label: 'Id';
-    readonly dataType: 'string';
-    readonly source: 'system';
-    readonly extraction: 'Row identity';
-    readonly enum: null;
-    readonly nullable: false;
-    readonly identifier: null;
+/**
+ * A ref to a table's row (13-data-model-v1 §11, 14-sequence-instance §16.1): `parent` is the row's
+ * owner (required, set once, decides loading and cascade delete; a parent row has any number of rows
+ * under it, 13-data-model-v1 §22.4); `lookup` is any other link. Write it with `parentRef(table)` /
+ * `lookupRef(table)`. `relatedName` names the way back, from the target row to the rows that point at
+ * it (`case_file.injuries`, 13-data-model-v1 §23.4 item 3); without it there is none.
+ */
+export type TableRef = {
+    table: string;
+    kind: 'parent' | 'lookup';
+    relatedName?: string;
 };
 export type CompanyNormalFieldDef = NormalFieldCore & {
+    /** Present only on reference fields. Always points at `{table}.id`. */
+    ref?: TableRef;
     /**
-     * Whether this field can reverse-look up a party.
-     * Sequence configs must not override this.
+     * No two rows of the table hold the same value (18-record-search-index §4.5); empty values do not
+     * count. `string` compares as written, `phone` / `email` as stored (E.164, lower-cased). The field
+     * can be an `upsert`'s `where`. Set when the field is added: once released it cannot be added or
+     * dropped (the compatibility check refuses it).
      */
-    identifier: null | {
-        kind: 'phone' | 'email';
-    };
-    /** Present only on reference fields. Always points at `{table}.id`. */
-    ref?: {
-        table: string;
-    };
+    unique?: true;
     deprecated?: boolean;
 };
-export type CompanyDerivedFieldDef = {
-    derived: true;
-    label: string;
-    dataType: DataType;
-    dependsOn: FieldPath[];
-    /** String name or `functions.<key>` registration object. */
-    computeFn: FuncRef;
-    deprecated?: boolean;
-};
-export type CompanyFieldDef = CompanyNormalFieldDef | CompanyDerivedFieldDef;
+export declare const normalFieldCoreSchema: z.ZodObject<{
+    label: z.ZodString;
+    dataType: z.ZodEnum<{
+        boolean: "boolean";
+        contact_schedule: "contact_schedule";
+        date: "date";
+        datetime: "datetime";
+        email: "email";
+        multi_select: "multi_select";
+        number: "number";
+        phone: "phone";
+        select: "select";
+        string: "string";
+        text: "text";
+        time: "time";
+    }>;
+    extraction: z.ZodString;
+    options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export declare const tableRefSchema: z.ZodObject<{
+    table: z.ZodString;
+    kind: z.ZodEnum<{
+        lookup: "lookup";
+        parent: "parent";
+    }>;
+    relatedName: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const companyNormalFieldDefSchema: z.ZodObject<{
+    label: z.ZodString;
+    dataType: z.ZodEnum<{
+        boolean: "boolean";
+        contact_schedule: "contact_schedule";
+        date: "date";
+        datetime: "datetime";
+        email: "email";
+        multi_select: "multi_select";
+        number: "number";
+        phone: "phone";
+        select: "select";
+        string: "string";
+        text: "text";
+        time: "time";
+    }>;
+    extraction: z.ZodString;
+    options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ref: z.ZodOptional<z.ZodObject<{
+        table: z.ZodString;
+        kind: z.ZodEnum<{
+            lookup: "lookup";
+            parent: "parent";
+        }>;
+        relatedName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    unique: z.ZodOptional<z.ZodLiteral<true>>;
+    deprecated: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const localTimeRangeSchema: z.ZodObject<{
+    start: z.ZodString;
+    end: z.ZodString;
+}, z.core.$strict>;
+export declare const weekdaySchema: z.ZodEnum<{
+    fri: "fri";
+    mon: "mon";
+    sat: "sat";
+    sun: "sun";
+    thu: "thu";
+    tue: "tue";
+    wed: "wed";
+}>;
+export declare const contactScheduleValueSchema: z.ZodObject<{
+    weekly: z.ZodNullable<z.ZodObject<{
+        mon: z.ZodArray<z.ZodObject<{
+            start: z.ZodString;
+            end: z.ZodString;
+        }, z.core.$strict>>;
+        tue: z.ZodArray<z.ZodObject<{
+            start: z.ZodString;
+            end: z.ZodString;
+        }, z.core.$strict>>;
+        wed: z.ZodArray<z.ZodObject<{
+            start: z.ZodString;
+            end: z.ZodString;
+        }, z.core.$strict>>;
+        thu: z.ZodArray<z.ZodObject<{
+            start: z.ZodString;
+            end: z.ZodString;
+        }, z.core.$strict>>;
+        fri: z.ZodArray<z.ZodObject<{
+            start: z.ZodString;
+            end: z.ZodString;
+        }, z.core.$strict>>;
+        sat: z.ZodArray<z.ZodObject<{
+            start: z.ZodString;
+            end: z.ZodString;
+        }, z.core.$strict>>;
+        sun: z.ZodArray<z.ZodObject<{
+            start: z.ZodString;
+            end: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    dateOverrides: z.ZodArray<z.ZodObject<{
+        dates: z.ZodArray<z.ZodString>;
+        windows: z.ZodArray<z.ZodObject<{
+            start: z.ZodString;
+            end: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type CompanyFieldDef = CompanyNormalFieldDef;
+/**
+ * A company table. Its rows are a list in a sequence's snapshot, except the sequence's business
+ * root, which is one row there.
+ */
 export type CompanyTableDef = {
     label: string;
-    rows: 'single' | 'multi';
     description: string;
     fields: Record<string, CompanyFieldDef>;
 };
 export type CompanySchema = Record<string, CompanyTableDef>;
-/** Usage-only overrides; structural keys are forbidden. */
-export type FieldOverride = {
-    label?: string;
-    description?: string;
-    extraction?: string;
-};
-/** Overlay on an inherited company table. Keys here override usage; other company fields stay as-is. */
-export type SequenceCompanyTableView = {
-    fields: Record<string, FieldOverride>;
-};
-/** Session is sequence-owned; always single-row; no derived / identifier. */
-export type SessionTableDef = {
-    label: string;
-    rows: 'single';
-    description: string;
-    fields: Record<string, NormalFieldCore>;
-};
-export type SequenceSlots = {
-    [table: string]: SequenceCompanyTableView | SessionTableDef | undefined;
-    session?: SessionTableDef;
-};
-/** Effective field shape used for Slots codegen. */
-export type EffectiveFieldDef = {
-    dataType: DataType;
-    enum: Array<string | number> | null;
-    nullable: boolean;
-    ref: null | {
-        table: string;
-    };
+export declare const companyFieldDefSchema: z.ZodObject<{
+    label: z.ZodString;
+    dataType: z.ZodEnum<{
+        boolean: "boolean";
+        contact_schedule: "contact_schedule";
+        date: "date";
+        datetime: "datetime";
+        email: "email";
+        multi_select: "multi_select";
+        number: "number";
+        phone: "phone";
+        select: "select";
+        string: "string";
+        text: "text";
+        time: "time";
+    }>;
+    extraction: z.ZodString;
+    options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    ref: z.ZodOptional<z.ZodObject<{
+        table: z.ZodString;
+        kind: z.ZodEnum<{
+            lookup: "lookup";
+            parent: "parent";
+        }>;
+        relatedName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    unique: z.ZodOptional<z.ZodLiteral<true>>;
+    deprecated: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const companyTableDefSchema: z.ZodObject<{
+    label: z.ZodString;
+    description: z.ZodString;
+    fields: z.ZodRecord<z.ZodString, z.ZodObject<{
+        label: z.ZodString;
+        dataType: z.ZodEnum<{
+            boolean: "boolean";
+            contact_schedule: "contact_schedule";
+            date: "date";
+            datetime: "datetime";
+            email: "email";
+            multi_select: "multi_select";
+            number: "number";
+            phone: "phone";
+            select: "select";
+            string: "string";
+            text: "text";
+            time: "time";
+        }>;
+        extraction: z.ZodString;
+        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ref: z.ZodOptional<z.ZodObject<{
+            table: z.ZodString;
+            kind: z.ZodEnum<{
+                lookup: "lookup";
+                parent: "parent";
+            }>;
+            relatedName: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        unique: z.ZodOptional<z.ZodLiteral<true>>;
+        deprecated: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const companySchemaSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    label: z.ZodString;
+    description: z.ZodString;
+    fields: z.ZodRecord<z.ZodString, z.ZodObject<{
+        label: z.ZodString;
+        dataType: z.ZodEnum<{
+            boolean: "boolean";
+            contact_schedule: "contact_schedule";
+            date: "date";
+            datetime: "datetime";
+            email: "email";
+            multi_select: "multi_select";
+            number: "number";
+            phone: "phone";
+            select: "select";
+            string: "string";
+            text: "text";
+            time: "time";
+        }>;
+        extraction: z.ZodString;
+        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        ref: z.ZodOptional<z.ZodObject<{
+            table: z.ZodString;
+            kind: z.ZodEnum<{
+                lookup: "lookup";
+                parent: "parent";
+            }>;
+            relatedName: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        unique: z.ZodOptional<z.ZodLiteral<true>>;
+        deprecated: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>>;
+/** A session field's types: simple values only, never `contact_schedule`. */
+export type SessionDataType = ScalarDataType;
+/**
+ * A session field (`schema/session.ts`, 11-remove-sequence-schema §3.1): what this conversation's
+ * talk filled or a function or action wrote. No `ref`, no `unique`: the session is
+ * related to no other table.
+ */
+export type SessionFieldDef = Omit<NormalFieldCore, 'dataType'> & {
+    dataType: SessionDataType;
+    deprecated?: boolean;
 };
-export type EffectiveTableDef = {
-    rows: 'single' | 'multi';
-    fields: Record<string, EffectiveFieldDef>;
+/** `schema/session.ts`: the conversation's own fields, for every sequence. */
+export type SessionSchema = {
+    fields: Record<string, SessionFieldDef>;
 };
-export type EffectiveSchema = Record<string, EffectiveTableDef>;
+/** A company with no `schema/session.ts`: sessions have no fields. */
+export declare const EMPTY_SESSION_SCHEMA: SessionSchema;
+export declare const sessionFieldDefSchema: z.ZodObject<{
+    label: z.ZodString;
+    extraction: z.ZodString;
+    options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    dataType: z.ZodEnum<{
+        boolean: "boolean";
+        date: "date";
+        datetime: "datetime";
+        email: "email";
+        multi_select: "multi_select";
+        number: "number";
+        phone: "phone";
+        select: "select";
+        string: "string";
+        text: "text";
+        time: "time";
+    }>;
+    deprecated: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const sessionSchemaSchema: z.ZodObject<{
+    fields: z.ZodRecord<z.ZodString, z.ZodObject<{
+        label: z.ZodString;
+        extraction: z.ZodString;
+        options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        dataType: z.ZodEnum<{
+            boolean: "boolean";
+            date: "date";
+            datetime: "datetime";
+            email: "email";
+            multi_select: "multi_select";
+            number: "number";
+            phone: "phone";
+            select: "select";
+            string: "string";
+            text: "text";
+            time: "time";
+        }>;
+        deprecated: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export declare const compiledCompanyMetadataSchema: z.ZodObject<{
+    tables: z.ZodRecord<z.ZodString, z.ZodObject<{
+        label: z.ZodString;
+        description: z.ZodString;
+        fields: z.ZodRecord<z.ZodString, z.ZodObject<{
+            label: z.ZodString;
+            dataType: z.ZodEnum<{
+                boolean: "boolean";
+                contact_schedule: "contact_schedule";
+                date: "date";
+                datetime: "datetime";
+                email: "email";
+                multi_select: "multi_select";
+                number: "number";
+                phone: "phone";
+                select: "select";
+                string: "string";
+                text: "text";
+                time: "time";
+            }>;
+            extraction: z.ZodString;
+            options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            ref: z.ZodOptional<z.ZodObject<{
+                table: z.ZodString;
+                kind: z.ZodEnum<{
+                    lookup: "lookup";
+                    parent: "parent";
+                }>;
+                relatedName: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+            unique: z.ZodOptional<z.ZodLiteral<true>>;
+            deprecated: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    session: z.ZodObject<{
+        fields: z.ZodRecord<z.ZodString, z.ZodObject<{
+            label: z.ZodString;
+            extraction: z.ZodString;
+            options: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            dataType: z.ZodEnum<{
+                boolean: "boolean";
+                date: "date";
+                datetime: "datetime";
+                email: "email";
+                multi_select: "multi_select";
+                number: "number";
+                phone: "phone";
+                select: "select";
+                string: "string";
+                text: "text";
+                time: "time";
+            }>;
+            deprecated: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export type CompiledCompanyMetadata = z.infer<typeof compiledCompanyMetadataSchema>;
+export declare function isCompanySchema(value: unknown): value is CompanySchema;
 //# sourceMappingURL=schema.d.ts.map