@plitzi/sdk-shared 0.30.19

package/dist/types/SchemaTypes.d.ts

@@ -0,0 +1,152 @@
+import { InteractionCallback, InteractionCallbackParamValues, InteractionCallbackType } from './InteractionTypes';
+import { Style } from './StyleTypes';
+import { RuleGroup } from '@plitzi/plitzi-ui/QueryBuilder';
+export type ElementRuntime = 'server' | 'client' | 'shared';
+export type ElementLoadStrategy = 'eager' | 'lazy' | 'visible';
+export type SchemaRsc = {
+    enabled?: boolean;
+    /** Wire protocol for RSC updates. 'json' is the default (data-only). 'stream' uses the RSC wire format (requires react-server condition). */
+    transport?: 'json' | 'stream';
+    /** Path for the RSC endpoint. Defaults to '/_rsc'. */
+    path?: string;
+};
+export type DropPosition = 'top' | 'bottom' | 'left' | 'right' | 'inside' | 'custom';
+export type BindingCategory = 'attributes' | 'style' | 'initialState';
+export type BindingTransformer = {
+    type: 'utility' | 'unknown';
+    action: string;
+    params: {
+        valueType: string;
+        value: string;
+    };
+};
+export type ElementBinding = {
+    id: string;
+    source: string;
+    fromPath?: string;
+    transformers?: BindingTransformer[];
+    when?: RuleGroup;
+    enabled?: boolean;
+    toPath: string;
+};
+export type ElementInteraction<T extends Record<keyof InteractionCallback['params'], unknown> = Record<string, unknown>> = {
+    id: string;
+    title: string;
+    type: InteractionCallbackType;
+    action: string;
+    params: InteractionCallbackParamValues<T>;
+    preview: Record<string, unknown>;
+    elementId: Element['id'];
+    beforeNode: string;
+    afterNode: string;
+    flowId: string;
+    enabled: boolean;
+    when?: RuleGroup;
+};
+export type ElementDefinition = {
+    rootId: Element['id'];
+    label: string;
+    type: string;
+    parentId?: Element['id'];
+    items?: Element['id'][];
+    styleSelectors: {
+        base: string;
+    } & Omit<Record<string, string>, 'base'>;
+    bindings?: Partial<Record<BindingCategory, ElementBinding[]>>;
+    interactions?: Record<string, ElementInteraction>;
+    initialState?: {
+        styleVariant?: Partial<Record<string, Partial<Record<string, string | string[]>>>>;
+        styleSelectors?: ElementDefinition['styleSelectors'];
+        visibility?: boolean;
+        [key: string]: unknown;
+    };
+    /** Where this element is rendered. 'server' = SSR only, 'client' = browser only, 'shared' = both (default). */
+    runtime?: ElementRuntime;
+    /** Controls when the element is loaded/rendered. */
+    loadStrategy?: ElementLoadStrategy;
+};
+export type Element<TAttributes extends Record<string, unknown> = Omit<{
+    [key: string]: unknown;
+}, 'subType'>> = {
+    id: string;
+    attributes: TAttributes & {
+        subType?: string;
+    };
+    definition: ElementDefinition;
+};
+export type SchemaVariable = {
+    name: string;
+    category: string;
+    type: 'text' | 'number' | 'email' | 'password' | 'select' | 'select2' | 'checkbox' | 'textarea' | 'color' | 'switch';
+    value: string;
+    subValues: {
+        when: RuleGroup;
+        value: string;
+    }[];
+};
+export type PageFolder = {
+    id: string;
+    name: string;
+    slug: string;
+    parentId?: PageFolder['id'];
+};
+export type Schema = {
+    flat: Record<string, Element>;
+    definition: {
+        name: string;
+        permanentUrl: string;
+    };
+    variables: SchemaVariable[];
+    settings: {
+        keepState?: boolean;
+        stateStorage?: 'localStorage' | 'sessionStorage';
+        customCss: string;
+        userProvider?: 'auth0' | 'basic' | 'custom' | '';
+        auth0Domain?: string;
+        auth0ClientId?: string;
+        tokenStorage?: 'localStorage' | 'sessionStorage' | '';
+        loginUrl?: string;
+        userUrl?: string;
+        refreshUrl?: string;
+        logoutUrl?: string;
+        detailsPath?: string;
+        tokenPath?: string;
+        expirationTimePath?: string;
+    };
+    rsc?: SchemaRsc;
+    pages: Element['id'][];
+    pageFolders: PageFolder[];
+};
+export type SchemaContextValue = {
+    definition?: {
+        rootId: string;
+    };
+    dispatchSchema?: unknown;
+    schemaUpdate?: (newSchema: SchemaRaw, fromSubscriptions?: boolean) => void;
+    schemaAddElement?: (to: string, data: Element, dropPosition?: DropPosition, initialItems?: Record<string, Element>, variables?: SchemaVariable[], fromSubscriptions?: boolean) => void;
+    schemaUpdateElement?: (element: Element, fromSubscriptions?: boolean) => void;
+    schemaMoveElement?: (from: string, to: string, elementId: string, dropPosition?: DropPosition, fromSubscriptions?: boolean) => void;
+    schemaCloneElement?: (elementId: string, targetId?: string, fromSubscriptions?: boolean) => void;
+    schemaRemoveElement?: (elementId: string, fromSubscriptions?: boolean) => void;
+    schemaAddPage?: (page: Element, fromSubscriptions?: boolean) => Promise<void>;
+    schemaHomePage?: (pageId: string, fromSubscriptions?: boolean) => void;
+    schemaUpdatePage?: (page: Element, fromSubscriptions?: boolean) => void;
+    schemaRemovePage?: (pageId: string, fromSubscriptions?: boolean) => void;
+    schemaAddPageFolder?: (pageFolder: PageFolder, fromSubscriptions?: boolean) => Promise<void>;
+    schemaUpdatePageFolder?: (pageFolder: PageFolder, fromSubscriptions?: boolean) => void;
+    schemaRemovePageFolder?: (pageFolderId: string, fromSubscriptions?: boolean) => void;
+    schemaAddVariable?: (variable: SchemaVariable, fromSubscriptions?: boolean) => void;
+    schemaUpdateVariable?: (variable: SchemaVariable, fromSubscriptions?: boolean) => void;
+    schemaRemoveVariable?: (name: string, fromSubscriptions?: boolean) => void;
+    schemaAddTemplate?: (to: string, data: Element, dropPosition?: DropPosition, initialItems?: Record<string, Element>, templatePlatform?: Style, variables?: SchemaVariable[], fromSubscriptions?: boolean) => void;
+    schemaUpdateSettings?: (value: string | number | boolean, path?: string, fromSubscriptions?: boolean) => void;
+};
+export type SchemaRaw = {
+    definition: Schema['definition'];
+    flat: Element[];
+    variables: SchemaVariable[];
+    settings: Schema['settings'];
+    rsc?: Schema['rsc'];
+    pages: Element['id'][];
+    pageFolders: PageFolder[];
+};

package/dist/types/SdkTypes.d.ts

@@ -0,0 +1,16 @@
+import { Collection } from './CollectionTypes';
+import { ComponentDefinition } from './ElementTypes';
+import { PluginRaw } from './PluginTypes';
+import { Schema } from './SchemaTypes';
+import { Segment } from './SegmentTypes';
+import { Style } from './StyleTypes';
+export type OfflineDataRaw = {
+    schema: Schema;
+    style: Style;
+    plugins?: PluginRaw[];
+    segments?: Record<string, Segment>;
+    collections?: Record<string, Collection>;
+};
+export type OfflineData = Omit<OfflineDataRaw, 'plugins'> & {
+    plugins: Record<string, ComponentDefinition>;
+};

package/dist/types/SegmentTypes.d.ts

@@ -0,0 +1,41 @@
+import { PageInfo } from './CollectionTypes';
+import { Element, Schema, SchemaRaw, SchemaVariable } from './SchemaTypes';
+import { Style } from './StyleTypes';
+export type Segment = {
+    id: string;
+    definition: {
+        name: string;
+        description: string;
+        baseElementId: Element['id'];
+    };
+    environment: 'main' | 'development' | 'staging' | 'production';
+    schema: Schema;
+    style: Style;
+    identifier: string;
+};
+export type BuilderSegmentsContextValue = {
+    dispatchSegments?: unknown;
+    segmentGet: (identifier: string) => Promise<Segment | undefined>;
+    segmentsFetch: (filter?: string | object, cursor?: string, limit?: number) => Promise<{
+        edges: Segment[];
+        pageInfo: PageInfo;
+    } | undefined | null>;
+    segmentsAdd: (segment: Segment) => void;
+    segmentsUpdate: (segment: Segment) => void;
+    segmentsRemove: (id: Segment['id']) => void;
+    elementAsSegment: (schema: Schema, style: Style, name: string, description: string, element: Element) => Promise<void>;
+    segmentAddMutation: (name: string, description: string, schema?: Schema, style?: Style, variables?: SchemaVariable[]) => Promise<void>;
+};
+export type SegmentsContextValue<T extends 'builder' | 'sdk' = 'sdk'> = T extends 'builder' ? BuilderSegmentsContextValue : Pick<BuilderSegmentsContextValue, 'segmentGet'>;
+export type SegmentRaw = {
+    id: string;
+    definition: {
+        name: string;
+        description: string;
+        baseElementId: Element['id'];
+    };
+    environment: 'main' | 'development' | 'staging' | 'production';
+    schema: SchemaRaw;
+    style: Style;
+    identifier: string;
+};

package/dist/types/ServerTypes.d.ts

@@ -0,0 +1,200 @@
+import { Environment } from './CommonTypes';
+import { McpServerConfig } from './McpTypes';
+import { OfflineDataRaw } from './SdkTypes';
+import { IncomingHttpHeaders } from 'node:http';
+import { FC } from 'react';
+export type ServerEnvironment = 'development' | 'production' | 'staging' | 'local';
+export type SSRHeaders = IncomingHttpHeaders & {
+    ':authority'?: string;
+    ':method'?: string;
+    ':path'?: string;
+    ':scheme'?: string;
+};
+export type SSRRequest = {
+    method: string;
+    path: string;
+    search: string;
+    url: string;
+    hostname: string;
+    protocol: 'http' | 'https';
+    headers: SSRHeaders;
+    query: Record<string, string>;
+    ctx: SSRContext;
+};
+export type SSRResponseHelpers = {
+    status: number;
+    headers: Record<string, string>;
+    setHeader: (name: string, value: string) => void;
+    setStatus: (code: number) => void;
+    send: (body: string) => void;
+    write: (chunk: string | Buffer) => void;
+    end: () => void;
+};
+export type SSRCredential = {
+    provider: string;
+    data: unknown;
+};
+export type PluginAction = 'copy' | 'compile' | 'download';
+export type PluginSourceFile<T = Record<string, unknown>> = {
+    js: string;
+    css?: string;
+    action?: PluginAction;
+    version?: string;
+    props?: T;
+};
+export type PluginSourceComponent<T = Record<string, unknown>> = {
+    component: unknown;
+    js?: string;
+    css?: string;
+    version?: string;
+    props?: T;
+};
+export type PluginSource<T = Record<string, unknown>> = PluginSourceFile<T> | PluginSourceComponent<T>;
+export type PluginEntry = {
+    name: string;
+    /** JS-safe identifier for the import statement (hyphens/dots replaced with underscores, no @version). */
+    varName: string;
+    /** SDK lookup key used as the object property (base name without @version). */
+    keyName: string;
+    /** Browser-facing URL served by the SSR server (e.g. /sdk-plugins/name@ver/index.js). */
+    js?: string;
+    /** Absolute filesystem path used for server-side dynamic import() during SSR. */
+    filePath?: string;
+    css?: string;
+    props: Record<string, unknown>;
+};
+export type SSRTemplateProps = {
+    title?: string;
+    jsPath?: string;
+    cssPath?: string;
+    builderJsPath?: string;
+    builderCssPath?: string;
+    plugins?: PluginEntry[];
+    react?: string;
+    reactJsx?: string;
+    reactDom?: string;
+    reactDomClient?: string;
+    /** When true the client-side <script> block is omitted — useful for inspecting raw SSR HTML. */
+    ssrOnly?: boolean;
+    debugMode?: boolean;
+};
+export type SSRPlugin = {
+    component: FC;
+    props: Record<string, unknown>;
+};
+export type SSRUser = {
+    token: string;
+    id: number;
+    username: string;
+    email: string;
+    verified: boolean;
+    permissions: string[];
+    roles: string[];
+};
+export type SSRSpaceDeployment = {
+    environment?: Environment;
+    credential?: SSRCredential;
+    spaceId?: number | null;
+    revision?: number;
+    templateProps?: SSRTemplateProps;
+    pluginNames?: string[];
+    pluginSources?: Record<string, PluginSource>;
+    error?: {
+        code: number;
+        message: string;
+    };
+};
+export type SSRTemplateFn = (params: SSRTemplateProps & {
+    html: string;
+    offlineData: string;
+}) => string;
+export type SSRRscData = {
+    /** Per-element server data keyed by schema element ID. Each element reads its own slice via its id prop. */
+    serverData?: Record<string, unknown>;
+};
+export type SSRAdapters = {
+    getOfflineData: (spaceId: number, environment: string, revision?: number) => Promise<OfflineDataRaw | undefined>;
+    getSpaceDeployment: (req: SSRRequest) => Promise<SSRSpaceDeployment>;
+    getUser?: (req: SSRRequest) => Promise<SSRUser | undefined>;
+    onLogin?: (req: SSRRequest) => Promise<boolean>;
+    onLogout?: (req: SSRRequest) => Promise<void>;
+    /** Called by the RSC endpoint to fetch server-side data for server components.
+     *  When `ids` is provided the adapter should return data only for those element IDs.
+     *  Omitting `ids` (initial SSR fetch or full refresh) must return data for all elements. */
+    getRscData?: (req: SSRRequest, spaceId: number, environment: Environment, revision: number, user: SSRUser | undefined, ids?: string[]) => Promise<SSRRscData>;
+};
+export type SSRRscConfig = {
+    /** Whether the RSC endpoint is active. Defaults to true when adapters.getRscData is provided. */
+    enabled?: boolean;
+    /** URL path for the RSC endpoint. Defaults to '/_rsc'. */
+    path?: string;
+    /** Server-side cache TTL for RSC responses in milliseconds. Defaults to 30 000. Set to 0 to disable. */
+    cacheTtlMs?: number;
+};
+export type SSRServerConfig = {
+    port?: number;
+    host?: string;
+    httpVersion?: 1 | 2 | 3;
+    tls?: {
+        key: Buffer | string;
+        cert: Buffer | string;
+        minVersion?: 'TLSv1' | 'TLSv1.1' | 'TLSv1.2' | 'TLSv1.3';
+    };
+    environment?: ServerEnvironment;
+    publicDir?: string;
+    static?: Record<string, string>;
+    devMode?: boolean;
+    cacheTtlMs?: number;
+    loginPath?: string | false;
+    middlewares?: SSRMiddleware[];
+    logoutPath?: string | false;
+    templateFn?: SSRTemplateFn;
+    plugins?: Record<string, PluginSource>;
+    pluginsCacheDir?: string;
+    pluginsTtlMs?: number;
+    /** Auto-download and cache plugins declared in the schema's offlineData.plugins list. Default: true. */
+    autoLoadSchemaPlugins?: boolean;
+    /** Omit client-side JS from the rendered page — useful for verifying SSR HTML without hydration. Default: false. */
+    ssrOnly?: boolean;
+    /** Stream HTML to the client as React renders, reducing TTFB. Default: false. */
+    streaming?: boolean;
+    /** Controls iframe embedding via CSP frame-ancestors (and X-Frame-Options for legacy browsers).
+     *  'DENY' — no site may embed this server (default).
+     *  'SAMEORIGIN' — only the same origin may embed it.
+     *  string[] — explicit list of allowed origins, e.g. ['https://app.example.com', 'https://preview.example.com'].
+     *  false — no restriction; headers are omitted. */
+    frameOptions?: 'DENY' | 'SAMEORIGIN' | string[] | false;
+    /** RSC (React Server Components) endpoint configuration. */
+    rsc?: SSRRscConfig;
+    /** MCP (Model Context Protocol) server configuration — exposes schema tools to Claude. */
+    mcp?: McpServerConfig;
+    adapters: SSRAdapters;
+    /** Cache-buster appended as ?v=<assetVersion> to all default SDK asset URLs (jsPath, cssPath, react vendor). Compute from file mtime or package version at startup. */
+    assetVersion?: string;
+};
+export type PluginRegistry = {
+    register: (name: string, source: PluginSource) => void;
+    invalidate: (name?: string, version?: string) => Promise<void>;
+};
+export type CacheFilter = {
+    spaceId?: number;
+    environment?: string;
+    hostname?: string;
+};
+export type CacheManager = {
+    invalidate: (filter?: CacheFilter) => number;
+    clear: () => void;
+    readonly size: number;
+};
+export type SSRMiddlewareNext = () => Promise<void> | void;
+export type SSRMiddleware = (req: SSRRequest, res: SSRResponseHelpers, next: SSRMiddlewareNext) => Promise<void> | void;
+export type SSRContext = {
+    spaceDeployment?: SSRSpaceDeployment;
+    user?: SSRUser;
+};
+export type SSRServer = {
+    listen: (port: number, host?: string) => void;
+    close: () => Promise<void>;
+    readonly cache: CacheManager | null;
+    readonly plugins: PluginRegistry;
+};

package/dist/types/SpaceTypes.d.ts

@@ -0,0 +1,25 @@
+import { Environment } from './CommonTypes';
+export type SpaceCredentialProvider = 's3' | 'r2' | 'ssr';
+export type SpaceCredential = {
+    identifier: string;
+    name: string;
+    provider: SpaceCredentialProvider;
+    inUse: boolean;
+    usedIn: {
+        usedFrom: string;
+        name: string;
+    }[];
+    createdAt: number;
+    updatedAt: number;
+};
+export type SpaceDeployment = {
+    id: number;
+    environment: Environment;
+    revision: number | null;
+    domain: string;
+    isVerified: boolean;
+    default: boolean;
+    credential: SpaceCredential | null;
+    createdAt: number;
+    updatedAt: number;
+};

package/dist/types/StateTypes.d.ts

@@ -0,0 +1,7 @@
+import { Dispatch, SetStateAction } from 'react';
+export type StateManagerContextValue = {
+    state: Record<string, unknown>;
+    setState: Dispatch<SetStateAction<Record<string, unknown>>>;
+    setStateByKey: (key: string, value: unknown, storeMode?: string) => void;
+    clearCache: (storeMode?: string) => void;
+};

package/dist/types/StoreTypes.d.ts

@@ -0,0 +1,22 @@
+import { Schema, Element } from './SchemaTypes';
+import { Segment } from './SegmentTypes';
+import { DisplayMode, Style, StyleState } from './StyleTypes';
+export type CommonState = {
+    prevSchema?: Schema;
+    schema: Schema;
+    pageDefinitions: Record<string, Element>;
+    style: Style;
+    segments: Record<string, Segment>;
+};
+export type BuilderState = CommonState & {
+    displayMode: DisplayMode;
+    selector?: string;
+    styleSelector?: string;
+    styleVariant?: string;
+    styleState?: StyleState;
+    elementHovered?: string;
+    elementSelected?: string;
+    setHovered: (elementId?: string) => void;
+    setSelected: (elementId?: string, iframeDOM?: HTMLIFrameElement | null, force?: boolean) => void;
+};
+export type SdkState = CommonState & {};

package/dist/types/StyleTypes.d.ts

@@ -0,0 +1,59 @@
+import { default as styleConstants } from '../style/styleConstants';
+export type TagType = 'class' | 'element' | 'id';
+export type DisplayMode = 'desktop' | 'tablet' | 'mobile';
+export type StyleMode = 'mobile-first' | 'desktop-first';
+export type StyleState = 'hover' | 'active' | 'focus' | 'disabled' | 'checked' | 'visited';
+export type StyleValue = number | string;
+export type StyleThemeMode = 'system' | 'light' | 'dark';
+export type StyleCategory = (typeof styleConstants)[keyof typeof styleConstants];
+export declare enum StyleVariableCategory {
+    COLOR = "color",
+    SPACING = "spacing",
+    SHADOW = "shadow",
+    CUSTOM = "custom"
+}
+export type StyleThemeValue = Partial<Record<Exclude<StyleThemeMode, 'system'> | 'default', string>>;
+export type StyleVariableValue = string | number | StyleThemeValue;
+export type StyleVariableGroup = Record<string, StyleVariableValue>;
+export type StyleVariables = Record<StyleVariableCategory, StyleVariableGroup>;
+export type StyleObject = Partial<Record<StyleCategory, StyleValue>>;
+export type StyleStates = Partial<Record<StyleState, StyleObject>>;
+export type StyleVariants = Record<string, Omit<StyleBlock, 'variants'>>;
+export type StyleBlock = {
+    default?: StyleObject;
+    states?: StyleStates;
+    variants?: StyleVariants;
+};
+export type StyleAttributes = Record<string, StyleBlock>;
+export type StyleItem = {
+    name: string;
+    type: TagType;
+    variables?: Partial<StyleVariables>;
+    attributes: StyleAttributes;
+    cache: string;
+    componentType?: string;
+};
+export type Style = {
+    platform: Record<DisplayMode, Record<string, StyleItem>>;
+    mode?: StyleMode;
+    theme: {
+        default: StyleThemeMode;
+        schemes: StyleThemeMode[];
+    };
+    variables: Partial<StyleVariables>;
+    cache: string;
+};
+export type StyleContextValue = {
+    styleUpdate?: unknown;
+    styleAddSelector?: unknown;
+    styleUpdateSelector?: unknown;
+    styleRemoveSelector?: unknown;
+    styleAddSelectorVariable?: unknown;
+    styleUpdateSelectorVariable?: unknown;
+    styleRemoveSelectorVariable?: unknown;
+    styleAddVariable?: unknown;
+    styleUpdateVariable?: unknown;
+    styleRemoveVariable?: unknown;
+    styleAddTemplate?: unknown;
+    styleUpdateSettings?: unknown;
+};

package/dist/types/StyleTypes.mjs

@@ -0,0 +1,6 @@
+//#region src/types/StyleTypes.ts
+var e = /* @__PURE__ */ function(e) {
+	return e.COLOR = "color", e.SPACING = "spacing", e.SHADOW = "shadow", e.CUSTOM = "custom", e;
+}({});
+//#endregion
+export { e as StyleVariableCategory };

package/dist/types/ThemeTypes.d.ts

@@ -0,0 +1,5 @@
+export type Theme = 'dark' | 'light' | 'system';
+export type ThemeContextValue = {
+    theme: Theme;
+    toggleTheme: () => void;
+};

package/dist/types/index.d.ts

@@ -0,0 +1,23 @@
+export * from './SchemaTypes';
+export * from './StyleTypes';
+export * from './InteractionTypes';
+export * from './PluginTypes';
+export * from './ElementTypes';
+export * from './DataSourceTypes';
+export * from './EventBridgeTypes';
+export * from './SegmentTypes';
+export * from './BuilderTypes';
+export * from './NavigationTypes';
+export * from './CollectionTypes';
+export * from './ComponentTypes';
+export * from './StateTypes';
+export * from './CommonTypes';
+export * from './AuthTypes';
+export * from './ResourceTypes';
+export * from './SdkTypes';
+export * from './SpaceTypes';
+export * from './DevToolsTypes';
+export * from './StoreTypes';
+export * from './ThemeTypes';
+export * from './McpTypes';
+export * from './ServerTypes';

package/dist/types/index.mjs

@@ -0,0 +1,2 @@
+import { StyleVariableCategory as e } from "./StyleTypes.mjs";
+export { e as StyleVariableCategory };