@flexkit/schema 0.0.0-stage → 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,304 @@
+import { z } from 'zod';
+
+type ScopeType = 'local' | 'global' | 'relationship';
+type DataType = 'cartesianpoint' | 'bigint' | 'boolean' | 'date' | 'datetime' | 'duration' | 'float' | 'id' | 'int' | 'point' | 'string' | 'time' | 'asset';
+type DefaultValueByDataType = {
+    asset: '';
+    bigint: string;
+    boolean: boolean | '';
+    cartesianpoint: string;
+    date: string;
+    datetime: string;
+    duration: string;
+    float: number | '';
+    id: string;
+    int: number | '';
+    point: string;
+    string: string;
+    time: string;
+};
+type DefaultValue<T extends DataType = DataType> = DefaultValueByDataType[T];
+type InputType = 'datetime' | 'editor' | 'asset' | 'number' | 'relationship' | 'select' | 'switch' | 'text' | 'textarea' | (string & NonNullable<unknown>);
+type PreviewType = 'boolean' | 'text' | 'number' | 'date' | 'datetime' | 'editor' | 'select' | 'relationship' | 'switch' | 'textarea'
+/** Filled stars for a numeric value; `options.max` sets the star count (default 5). */
+ | 'rating' | (string & NonNullable<unknown>);
+type SelectList = {
+    label: string;
+    value: string;
+};
+type GroupedSelectList = {
+    groupLabel: string;
+    items: SelectList[];
+};
+type CommonOptions = {
+    comment?: string;
+    size?: number;
+    placeholder?: string;
+};
+type SelectOptions = CommonOptions & {
+    list: SelectList[] | GroupedSelectList[];
+};
+type AssetOptions = CommonOptions & {
+    accept?: string;
+};
+type RelationshipOptions = CommonOptions & {
+    accept?: string;
+};
+type DateTimeOptions = CommonOptions & {
+    format?: string;
+};
+type NumberOptions = CommonOptions & {
+    min?: number;
+    /** Upper bound; also the number of stars when `previewType` is `'rating'`. */
+    max?: number;
+};
+type AttributeOptions = {
+    select: SelectOptions;
+    asset: AssetOptions;
+    datetime: DateTimeOptions;
+    number: NumberOptions;
+    relationship: RelationshipOptions;
+    text: CommonOptions;
+    textarea: CommonOptions;
+    switch: CommonOptions;
+    [key: string]: CommonOptions;
+};
+/**
+ * Authoring form of an attribute's validation: a function that receives the
+ * Zod namespace and returns a schema. `flexkit deploy` compiles it to JSON
+ * Schema; only what JSON Schema can express survives (no `refine`, no
+ * `transform`, no async checks).
+ */
+type ZodValidation = (zod: typeof z) => z.ZodType;
+/** A JSON Schema (draft-07) fragment, as stored by the backend and read by the Studio. */
+type JsonSchemaObject = {
+    [key: string]: unknown;
+};
+type AttributeBaseOf<TValidation> = {
+    inputType: InputType;
+    previewType?: PreviewType;
+    /**
+     * Hide the field in the form and the list column. Distinct from
+     * `entity.menu.hidden`.
+     */
+    hidden?: boolean;
+    /**
+     * Make the field read-only in the form. Read-only attributes are omitted
+     * from create/update mutations sent by the Studio and skipped during form
+     * validation.
+     */
+    readOnly?: boolean;
+    /**
+     * Marks uniqueness intent. Enforced at deploy for global non-asset attributes.
+     */
+    unique?: boolean;
+    /**
+     * Require a value at the API level: the generated GraphQL field is non-null.
+     * Applies to global scalar attributes.
+     */
+    isRequired?: boolean;
+    /**
+     * Include this attribute in search indexing and the global search UI.
+     */
+    searchable?: boolean;
+    /**
+     * Field group name(s) this attribute belongs to. Distinct from
+     * `entity.menu.group`, which is the sidebar section.
+     */
+    group?: string | string[];
+    label: string;
+    name: string;
+    options?: AttributeOptions[InputType];
+    relationship?: {
+        entity: string;
+        mode: 'single' | 'multiple';
+        field: string;
+    };
+    validation?: TValidation;
+};
+/**
+ * Space codes that can read/write this attribute. Members of any listed
+ * space have access; users outside all listed spaces cannot see the value.
+ *
+ * Not allowed on relationship attributes (`scope: 'relationship'`): bind the
+ * related entity to the space instead.
+ */
+type AttributeSpaces = {
+    spaces?: string[];
+};
+type AttributeScopeAndSpaces = {
+    scope: 'relationship';
+    spaces?: never;
+} | ({
+    scope: 'local' | 'global';
+} & AttributeSpaces);
+type AttributeByDataTypeOf<T extends DataType, TValidation> = AttributeBaseOf<TValidation> & {
+    dataType: T;
+    defaultValue?: DefaultValueByDataType[T];
+} & (T extends 'asset' ? {
+    scope?: 'global';
+} & AttributeSpaces : AttributeScopeAndSpaces);
+type AttributeOf<TValidation> = {
+    [T in DataType]: AttributeByDataTypeOf<T, TValidation>;
+}[DataType];
+/** Attribute as written in `flexkit.config.ts`. */
+type Attribute = AttributeOf<ZodValidation>;
+/** Attribute as deployed and served by the backend (validation is JSON Schema). */
+type UiAttribute = AttributeOf<JsonSchemaObject>;
+/**
+ * Form-only tab that groups attributes in the edit/add drawer.
+ * Distinct from `entity.menu.group` (sidebar section).
+ */
+type FieldGroup = {
+    name: string;
+    /**
+     * Tab label. Required for custom groups. Optional for the reserved
+     * `all` tab; Studio uses `All fields` when it is omitted.
+     */
+    title?: string;
+    /** Lucide icon name in PascalCase, e.g. `'Tag'`. */
+    icon?: string;
+    default?: boolean;
+    hidden?: boolean;
+};
+/** Sidebar placement of an entity in the Studio. */
+type EntityMenu = {
+    /** Leave the entity out of the sidebar. */
+    hidden?: boolean;
+    label?: string;
+    /** Name of a `menuGroups` entry of the project. */
+    group?: string;
+    /** Lucide icon name in PascalCase, e.g. `'Tag'`. */
+    icon?: string;
+};
+type EntityOf<TAttribute> = {
+    name: string;
+    plural: string;
+    /**
+     * Attribute name used as the human-readable label in relationship previews,
+     * search hits, and edit-drawer titles. Must match an attribute `name`.
+     * Falls back to the first attribute when omitted. The effective display
+     * attribute cannot be space-bound.
+     */
+    display?: string;
+    menu?: EntityMenu;
+    /**
+     * Space codes that can access this entity. Members of any listed space have
+     * access; users outside all listed spaces cannot see the entity at all.
+     */
+    spaces?: string[];
+    /**
+     * Form field groups rendered as tabs. Does not change storage.
+     * Distinct from `menu.group` (sidebar section).
+     */
+    groups?: FieldGroup[];
+    attributes: TAttribute[];
+};
+/** Entity as written in `flexkit.config.ts`. */
+type Entity = EntityOf<Attribute>;
+/** Entity as deployed and served by the backend. */
+type UiEntity = EntityOf<UiAttribute>;
+type Schema = Entity[];
+type UiSchema = UiEntity[];
+type Scope = {
+    name: string;
+    label: string;
+    isDefault?: boolean;
+    sortOrder?: number;
+};
+type Scopes = Scope[];
+type Space = {
+    code: string;
+    label: string;
+};
+type Spaces = Space[];
+type MenuGroup = {
+    name: string;
+    title: string;
+};
+/** One project in `flexkit.config.ts`. */
+interface ProjectConfig {
+    /** Studio title shown in the navbar. Falls back to the dashboard project name. */
+    title?: string;
+    projectId: string;
+    /** Sidebar sections; entities join one through `menu.group`. */
+    menuGroups?: MenuGroup[];
+    scopes?: Scopes;
+    /**
+     * Permission spaces for this project. Spaces scope access to entities,
+     * attributes and app resources (automations, skills, agents). Membership is
+     * assigned to project members in the Flexkit Dashboard after deploy.
+     */
+    spaces?: Spaces;
+    schema: Entity[];
+}
+type Config = ProjectConfig | ProjectConfig[];
+/** The deployable form of a project config: what `flexkit deploy` sends. */
+interface UiProjectSchema {
+    title?: string;
+    projectId: string;
+    menuGroups?: MenuGroup[];
+    scopes?: Scopes;
+    spaces?: Spaces;
+    schema: UiEntity[];
+}
+/** Response of `GET /<projectId>/api/schema`: what the Studio renders from. */
+interface ProjectSchemaResponse {
+    projectId: string;
+    title: string;
+    menuGroups: MenuGroup[];
+    scopes: Scopes;
+    spaces: Spaces;
+    schema: UiEntity[];
+    schemaHash: string | null;
+}
+
+/** Types and returns a `flexkit.config.ts` export unchanged. */
+declare function defineConfig<T extends Config>(config: T): T;
+/**
+ * Types an entity and normalizes it: asset attributes get `scope: 'global'`,
+ * and invalid asset scopes or display attributes throw at config load time.
+ */
+declare function defineEntity<T extends Entity>(entity: T): Entity;
+
+declare function normalizeEntity(entity: Entity): Entity;
+
+/** Removes `$schema` at every level of a JSON Schema document. */
+declare function stripJsonSchemaMeta(value: unknown): unknown;
+
+/**
+ * JSON Schema keywords the Studio form knows how to validate. Anything else
+ * fails the deploy so a rule never silently disappears between the config and
+ * the form.
+ */
+declare const SUPPORTED_VALIDATION_KEYWORDS: ReadonlySet<string>;
+declare const SUPPORTED_VALIDATION_FORMATS: ReadonlySet<string>;
+type SerializationLocation = {
+    entity?: string;
+    attribute?: string;
+};
+/** Raised when a config cannot be turned into a deployable JSON schema. */
+declare class SchemaSerializationError extends Error {
+    readonly entity: string | undefined;
+    readonly attribute: string | undefined;
+    constructor(reason: string, location?: SerializationLocation, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Compiles an attribute's Zod validation to a JSON Schema (draft-07) fragment.
+ * Throws `SchemaSerializationError` for anything the Studio cannot enforce.
+ */
+declare function serializeValidation(validation: ZodValidation, location?: SerializationLocation): JsonSchemaObject;
+declare function serializeAttribute(attribute: Attribute, entityName: string): UiAttribute;
+declare function serializeEntity(entity: Entity): UiEntity;
+/**
+ * Turns one project of a `flexkit.config.ts` into the payload `flexkit deploy`
+ * sends. Only data survives: title, projectId, menuGroups, scopes, spaces and
+ * the schema with validation compiled to JSON Schema.
+ */
+declare function serializeProjectConfig(project: ProjectConfig): UiProjectSchema;
+/** Serializes a whole `flexkit.config.ts` export (one project or a list). */
+declare function serializeConfig(config: Config): UiProjectSchema[];
+
+export { type AssetOptions, type Attribute, type AttributeOf, type AttributeOptions, type CommonOptions, type Config, type DataType, type DateTimeOptions, type DefaultValue, type DefaultValueByDataType, type Entity, type EntityMenu, type EntityOf, type FieldGroup, type GroupedSelectList, type InputType, type JsonSchemaObject, type MenuGroup, type NumberOptions, type PreviewType, type ProjectConfig, type ProjectSchemaResponse, type RelationshipOptions, SUPPORTED_VALIDATION_FORMATS, SUPPORTED_VALIDATION_KEYWORDS, type Schema, SchemaSerializationError, type Scope, type ScopeType, type Scopes, type SelectList, type SelectOptions, type Space, type Spaces, type UiAttribute, type UiEntity, type UiProjectSchema, type UiSchema, type ZodValidation, defineConfig, defineEntity, normalizeEntity, serializeAttribute, serializeConfig, serializeEntity, serializeProjectConfig, serializeValidation, stripJsonSchemaMeta };

package/dist/index.d.ts

@@ -0,0 +1,304 @@
+import { z } from 'zod';
+
+type ScopeType = 'local' | 'global' | 'relationship';
+type DataType = 'cartesianpoint' | 'bigint' | 'boolean' | 'date' | 'datetime' | 'duration' | 'float' | 'id' | 'int' | 'point' | 'string' | 'time' | 'asset';
+type DefaultValueByDataType = {
+    asset: '';
+    bigint: string;
+    boolean: boolean | '';
+    cartesianpoint: string;
+    date: string;
+    datetime: string;
+    duration: string;
+    float: number | '';
+    id: string;
+    int: number | '';
+    point: string;
+    string: string;
+    time: string;
+};
+type DefaultValue<T extends DataType = DataType> = DefaultValueByDataType[T];
+type InputType = 'datetime' | 'editor' | 'asset' | 'number' | 'relationship' | 'select' | 'switch' | 'text' | 'textarea' | (string & NonNullable<unknown>);
+type PreviewType = 'boolean' | 'text' | 'number' | 'date' | 'datetime' | 'editor' | 'select' | 'relationship' | 'switch' | 'textarea'
+/** Filled stars for a numeric value; `options.max` sets the star count (default 5). */
+ | 'rating' | (string & NonNullable<unknown>);
+type SelectList = {
+    label: string;
+    value: string;
+};
+type GroupedSelectList = {
+    groupLabel: string;
+    items: SelectList[];
+};
+type CommonOptions = {
+    comment?: string;
+    size?: number;
+    placeholder?: string;
+};
+type SelectOptions = CommonOptions & {
+    list: SelectList[] | GroupedSelectList[];
+};
+type AssetOptions = CommonOptions & {
+    accept?: string;
+};
+type RelationshipOptions = CommonOptions & {
+    accept?: string;
+};
+type DateTimeOptions = CommonOptions & {
+    format?: string;
+};
+type NumberOptions = CommonOptions & {
+    min?: number;
+    /** Upper bound; also the number of stars when `previewType` is `'rating'`. */
+    max?: number;
+};
+type AttributeOptions = {
+    select: SelectOptions;
+    asset: AssetOptions;
+    datetime: DateTimeOptions;
+    number: NumberOptions;
+    relationship: RelationshipOptions;
+    text: CommonOptions;
+    textarea: CommonOptions;
+    switch: CommonOptions;
+    [key: string]: CommonOptions;
+};
+/**
+ * Authoring form of an attribute's validation: a function that receives the
+ * Zod namespace and returns a schema. `flexkit deploy` compiles it to JSON
+ * Schema; only what JSON Schema can express survives (no `refine`, no
+ * `transform`, no async checks).
+ */
+type ZodValidation = (zod: typeof z) => z.ZodType;
+/** A JSON Schema (draft-07) fragment, as stored by the backend and read by the Studio. */
+type JsonSchemaObject = {
+    [key: string]: unknown;
+};
+type AttributeBaseOf<TValidation> = {
+    inputType: InputType;
+    previewType?: PreviewType;
+    /**
+     * Hide the field in the form and the list column. Distinct from
+     * `entity.menu.hidden`.
+     */
+    hidden?: boolean;
+    /**
+     * Make the field read-only in the form. Read-only attributes are omitted
+     * from create/update mutations sent by the Studio and skipped during form
+     * validation.
+     */
+    readOnly?: boolean;
+    /**
+     * Marks uniqueness intent. Enforced at deploy for global non-asset attributes.
+     */
+    unique?: boolean;
+    /**
+     * Require a value at the API level: the generated GraphQL field is non-null.
+     * Applies to global scalar attributes.
+     */
+    isRequired?: boolean;
+    /**
+     * Include this attribute in search indexing and the global search UI.
+     */
+    searchable?: boolean;
+    /**
+     * Field group name(s) this attribute belongs to. Distinct from
+     * `entity.menu.group`, which is the sidebar section.
+     */
+    group?: string | string[];
+    label: string;
+    name: string;
+    options?: AttributeOptions[InputType];
+    relationship?: {
+        entity: string;
+        mode: 'single' | 'multiple';
+        field: string;
+    };
+    validation?: TValidation;
+};
+/**
+ * Space codes that can read/write this attribute. Members of any listed
+ * space have access; users outside all listed spaces cannot see the value.
+ *
+ * Not allowed on relationship attributes (`scope: 'relationship'`): bind the
+ * related entity to the space instead.
+ */
+type AttributeSpaces = {
+    spaces?: string[];
+};
+type AttributeScopeAndSpaces = {
+    scope: 'relationship';
+    spaces?: never;
+} | ({
+    scope: 'local' | 'global';
+} & AttributeSpaces);
+type AttributeByDataTypeOf<T extends DataType, TValidation> = AttributeBaseOf<TValidation> & {
+    dataType: T;
+    defaultValue?: DefaultValueByDataType[T];
+} & (T extends 'asset' ? {
+    scope?: 'global';
+} & AttributeSpaces : AttributeScopeAndSpaces);
+type AttributeOf<TValidation> = {
+    [T in DataType]: AttributeByDataTypeOf<T, TValidation>;
+}[DataType];
+/** Attribute as written in `flexkit.config.ts`. */
+type Attribute = AttributeOf<ZodValidation>;
+/** Attribute as deployed and served by the backend (validation is JSON Schema). */
+type UiAttribute = AttributeOf<JsonSchemaObject>;
+/**
+ * Form-only tab that groups attributes in the edit/add drawer.
+ * Distinct from `entity.menu.group` (sidebar section).
+ */
+type FieldGroup = {
+    name: string;
+    /**
+     * Tab label. Required for custom groups. Optional for the reserved
+     * `all` tab; Studio uses `All fields` when it is omitted.
+     */
+    title?: string;
+    /** Lucide icon name in PascalCase, e.g. `'Tag'`. */
+    icon?: string;
+    default?: boolean;
+    hidden?: boolean;
+};
+/** Sidebar placement of an entity in the Studio. */
+type EntityMenu = {
+    /** Leave the entity out of the sidebar. */
+    hidden?: boolean;
+    label?: string;
+    /** Name of a `menuGroups` entry of the project. */
+    group?: string;
+    /** Lucide icon name in PascalCase, e.g. `'Tag'`. */
+    icon?: string;
+};
+type EntityOf<TAttribute> = {
+    name: string;
+    plural: string;
+    /**
+     * Attribute name used as the human-readable label in relationship previews,
+     * search hits, and edit-drawer titles. Must match an attribute `name`.
+     * Falls back to the first attribute when omitted. The effective display
+     * attribute cannot be space-bound.
+     */
+    display?: string;
+    menu?: EntityMenu;
+    /**
+     * Space codes that can access this entity. Members of any listed space have
+     * access; users outside all listed spaces cannot see the entity at all.
+     */
+    spaces?: string[];
+    /**
+     * Form field groups rendered as tabs. Does not change storage.
+     * Distinct from `menu.group` (sidebar section).
+     */
+    groups?: FieldGroup[];
+    attributes: TAttribute[];
+};
+/** Entity as written in `flexkit.config.ts`. */
+type Entity = EntityOf<Attribute>;
+/** Entity as deployed and served by the backend. */
+type UiEntity = EntityOf<UiAttribute>;
+type Schema = Entity[];
+type UiSchema = UiEntity[];
+type Scope = {
+    name: string;
+    label: string;
+    isDefault?: boolean;
+    sortOrder?: number;
+};
+type Scopes = Scope[];
+type Space = {
+    code: string;
+    label: string;
+};
+type Spaces = Space[];
+type MenuGroup = {
+    name: string;
+    title: string;
+};
+/** One project in `flexkit.config.ts`. */
+interface ProjectConfig {
+    /** Studio title shown in the navbar. Falls back to the dashboard project name. */
+    title?: string;
+    projectId: string;
+    /** Sidebar sections; entities join one through `menu.group`. */
+    menuGroups?: MenuGroup[];
+    scopes?: Scopes;
+    /**
+     * Permission spaces for this project. Spaces scope access to entities,
+     * attributes and app resources (automations, skills, agents). Membership is
+     * assigned to project members in the Flexkit Dashboard after deploy.
+     */
+    spaces?: Spaces;
+    schema: Entity[];
+}
+type Config = ProjectConfig | ProjectConfig[];
+/** The deployable form of a project config: what `flexkit deploy` sends. */
+interface UiProjectSchema {
+    title?: string;
+    projectId: string;
+    menuGroups?: MenuGroup[];
+    scopes?: Scopes;
+    spaces?: Spaces;
+    schema: UiEntity[];
+}
+/** Response of `GET /<projectId>/api/schema`: what the Studio renders from. */
+interface ProjectSchemaResponse {
+    projectId: string;
+    title: string;
+    menuGroups: MenuGroup[];
+    scopes: Scopes;
+    spaces: Spaces;
+    schema: UiEntity[];
+    schemaHash: string | null;
+}
+
+/** Types and returns a `flexkit.config.ts` export unchanged. */
+declare function defineConfig<T extends Config>(config: T): T;
+/**
+ * Types an entity and normalizes it: asset attributes get `scope: 'global'`,
+ * and invalid asset scopes or display attributes throw at config load time.
+ */
+declare function defineEntity<T extends Entity>(entity: T): Entity;
+
+declare function normalizeEntity(entity: Entity): Entity;
+
+/** Removes `$schema` at every level of a JSON Schema document. */
+declare function stripJsonSchemaMeta(value: unknown): unknown;
+
+/**
+ * JSON Schema keywords the Studio form knows how to validate. Anything else
+ * fails the deploy so a rule never silently disappears between the config and
+ * the form.
+ */
+declare const SUPPORTED_VALIDATION_KEYWORDS: ReadonlySet<string>;
+declare const SUPPORTED_VALIDATION_FORMATS: ReadonlySet<string>;
+type SerializationLocation = {
+    entity?: string;
+    attribute?: string;
+};
+/** Raised when a config cannot be turned into a deployable JSON schema. */
+declare class SchemaSerializationError extends Error {
+    readonly entity: string | undefined;
+    readonly attribute: string | undefined;
+    constructor(reason: string, location?: SerializationLocation, options?: {
+        cause?: unknown;
+    });
+}
+/**
+ * Compiles an attribute's Zod validation to a JSON Schema (draft-07) fragment.
+ * Throws `SchemaSerializationError` for anything the Studio cannot enforce.
+ */
+declare function serializeValidation(validation: ZodValidation, location?: SerializationLocation): JsonSchemaObject;
+declare function serializeAttribute(attribute: Attribute, entityName: string): UiAttribute;
+declare function serializeEntity(entity: Entity): UiEntity;
+/**
+ * Turns one project of a `flexkit.config.ts` into the payload `flexkit deploy`
+ * sends. Only data survives: title, projectId, menuGroups, scopes, spaces and
+ * the schema with validation compiled to JSON Schema.
+ */
+declare function serializeProjectConfig(project: ProjectConfig): UiProjectSchema;
+/** Serializes a whole `flexkit.config.ts` export (one project or a list). */
+declare function serializeConfig(config: Config): UiProjectSchema[];
+
+export { type AssetOptions, type Attribute, type AttributeOf, type AttributeOptions, type CommonOptions, type Config, type DataType, type DateTimeOptions, type DefaultValue, type DefaultValueByDataType, type Entity, type EntityMenu, type EntityOf, type FieldGroup, type GroupedSelectList, type InputType, type JsonSchemaObject, type MenuGroup, type NumberOptions, type PreviewType, type ProjectConfig, type ProjectSchemaResponse, type RelationshipOptions, SUPPORTED_VALIDATION_FORMATS, SUPPORTED_VALIDATION_KEYWORDS, type Schema, SchemaSerializationError, type Scope, type ScopeType, type Scopes, type SelectList, type SelectOptions, type Space, type Spaces, type UiAttribute, type UiEntity, type UiProjectSchema, type UiSchema, type ZodValidation, defineConfig, defineEntity, normalizeEntity, serializeAttribute, serializeConfig, serializeEntity, serializeProjectConfig, serializeValidation, stripJsonSchemaMeta };