@almadar/sdk 0.1.0-alpha.4 → 0.2.0

package/dist/react/index.d.ts

@@ -1,9 +1,29 @@
-import * as react from 'react';
-import { a as AlmadarAppProps, b as AlmadarAppRef } from '../types-BfWDIOGm.js';
-export { A as AgentEvent } from '../types-BfWDIOGm.js';
+export { A as AlmadarApp } from '../AlmadarApp-DgwtnIRy.js';
+import react__default from 'react';
+import { OrbitalSchema } from '@almadar/core';
+export { EntityData, EventPayload, OrbitalSchema, SSEEvent } from '@almadar/core';
 export { useEventBus as useOrbBus } from '@almadar/ui/hooks';
-export { EntityData, EventPayload, OrbitalSchema } from '@almadar/core';
+export { A as AlmadarAppProps, O as OrbitalConfigPanelProps } from '../types-C6RJADoY.js';
 
-declare const AlmadarApp: react.ForwardRefExoticComponent<AlmadarAppProps & react.RefAttributes<AlmadarAppRef>>;
+/**
+ * OrbitalConfigPanel — auto-derived control rail for an orbital schema.
+ *
+ * Finds the first trait that declares a non-empty `config`, filters its fields
+ * by the consumer-supplied `exposedTiers`, and renders `@almadar/ui`'s
+ * `PropertyInspector`. Every control change deep-clones the schema, writes the
+ * new value into the matching field's `default`, and emits the mutated schema
+ * so the host can pass it to `OrbPreview`.
+ */
 
-export { AlmadarApp, AlmadarAppProps, AlmadarAppRef };
+interface OrbitalConfigPanelProps {
+    schema: string | OrbitalSchema;
+    exposedTiers?: string[];
+    position?: 'right' | 'bottom';
+    onSchemaChange?: (schema: OrbitalSchema) => void;
+}
+declare function OrbitalConfigPanel({ schema, exposedTiers, position, onSchemaChange, }: OrbitalConfigPanelProps): react__default.ReactElement | null;
+declare namespace OrbitalConfigPanel {
+    var displayName: string;
+}
+
+export { OrbitalConfigPanel };

package/dist/react/index.js

@@ -1,9 +1,92 @@
-import { lazy, forwardRef, useRef, useImperativeHandle, Suspense } from 'react';
+import { lazy, useMemo, useState, useEffect, Suspense } from 'react';
+import { Box, Stack, Typography, PropertyInspector } from '@almadar/ui/components';
+import { jsx, jsxs } from 'react/jsx-runtime';
 import '@almadar/ui/index.css';
-import { jsx } from 'react/jsx-runtime';
 export { useEventBus as useOrbBus } from '@almadar/ui/hooks';
 
 // src/react/AlmadarApp.tsx
+function parseSchema(schema) {
+  if (typeof schema === "string") {
+    return JSON.parse(schema);
+  }
+  return schema;
+}
+function deepClone(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function findConfigTrait(schema) {
+  if (!schema?.orbitals) return null;
+  for (const orbital of schema.orbitals) {
+    for (const traitRef of orbital.traits ?? []) {
+      if (typeof traitRef !== "object" || traitRef === null) continue;
+      const trait = traitRef;
+      if (trait.config && Object.keys(trait.config).length > 0) {
+        const name = "name" in trait && typeof trait.name === "string" ? trait.name : "Config";
+        return { name, config: trait.config };
+      }
+    }
+  }
+  return null;
+}
+function applyConfigOverride(schema, field, value) {
+  const next = deepClone(schema);
+  for (const orbital of next.orbitals ?? []) {
+    for (const traitRef of orbital.traits ?? []) {
+      if (typeof traitRef !== "object" || traitRef === null) continue;
+      const trait = traitRef;
+      if (trait.config && field in trait.config) {
+        trait.config[field] = { ...trait.config[field], default: value };
+        return next;
+      }
+    }
+  }
+  return next;
+}
+function OrbitalConfigPanel({
+  schema,
+  exposedTiers,
+  position = "right",
+  onSchemaChange
+}) {
+  const parsed = useMemo(() => parseSchema(schema), [schema]);
+  const target = useMemo(() => findConfigTrait(parsed), [parsed]);
+  const [values, setValues] = useState({});
+  if (!target) return null;
+  const sortedConfig = Object.fromEntries(
+    Object.entries(target.config).sort(([a], [b]) => a.localeCompare(b))
+  );
+  const handleChange = (field, value) => {
+    setValues((prev) => ({ ...prev, [field]: value }));
+    const nextSchema = applyConfigOverride(parsed, field, value);
+    onSchemaChange?.(nextSchema);
+  };
+  const handleReset = () => {
+    setValues({});
+    onSchemaChange?.(parsed);
+  };
+  const isHorizontal = position === "bottom";
+  return /* @__PURE__ */ jsx(
+    Box,
+    {
+      className: `${isHorizontal ? "w-full border-t" : "h-full w-80 flex-shrink-0 border-l"} border-border bg-card p-3 overflow-y-auto`,
+      children: /* @__PURE__ */ jsxs(Stack, { direction: "vertical", gap: "sm", children: [
+        /* @__PURE__ */ jsx(Typography, { variant: "caption", weight: "bold", color: "muted", children: "Controls" }),
+        /* @__PURE__ */ jsx(
+          PropertyInspector,
+          {
+            title: target.name,
+            config: sortedConfig,
+            values,
+            onChange: handleChange,
+            onReset: handleReset,
+            tiers: exposedTiers
+          }
+        )
+      ] })
+    }
+  );
+}
+OrbitalConfigPanel.displayName = "OrbitalConfigPanel";
 var OrbPreviewLazy = lazy(async () => {
   const mod = await import('@almadar/ui/runtime');
   return { default: mod.OrbPreview };
@@ -12,19 +95,25 @@ var BrowserPlaygroundLazy = lazy(async () => {
   const mod = await import('@almadar/ui/runtime');
   return { default: mod.BrowserPlayground };
 });
-var AlmadarApp = forwardRef(function AlmadarApp2(props, ref) {
-  const emitterRef = useRef(null);
-  useImperativeHandle(ref, () => ({
-    emit(event, payload) {
-      if (emitterRef.current === null) return;
-      emitterRef.current(event, payload);
-    }
-  }));
+function parseSchema2(schema) {
+  if (typeof schema === "string") {
+    return JSON.parse(schema);
+  }
+  return schema;
+}
+function AlmadarApp(props) {
   const mode = props.mode ?? "static";
-  return /* @__PURE__ */ jsx(Suspense, { fallback: null, children: mode === "mock" ? /* @__PURE__ */ jsx(
+  const parsedSchema = useMemo(() => parseSchema2(props.schema), [props.schema]);
+  const [controlledSchema, setControlledSchema] = useState(parsedSchema);
+  useEffect(() => {
+    setControlledSchema(parsedSchema);
+  }, [parsedSchema]);
+  const effectiveSchema = props.exposedTiers && mode !== "server" ? controlledSchema : parsedSchema;
+  const showControls = props.exposedTiers && props.exposedTiers.length > 0 && mode !== "server";
+  const preview = mode === "mock" ? /* @__PURE__ */ jsx(
     BrowserPlaygroundLazy,
     {
-      schema: props.schema,
+      schema: effectiveSchema,
       mode: "mock",
       initialPagePath: props.initialPagePath,
       height: props.height,
@@ -33,17 +122,40 @@ var AlmadarApp = forwardRef(function AlmadarApp2(props, ref) {
   ) : /* @__PURE__ */ jsx(
     OrbPreviewLazy,
     {
-      schema: props.schema,
+      schema: effectiveSchema,
       mockData: props.data,
       serverUrl: props.serverUrl,
       initialPagePath: props.initialPagePath,
       height: props.height,
       className: props.className
     }
+  );
+  if (!showControls) {
+    return /* @__PURE__ */ jsx(Suspense, { fallback: null, children: preview });
+  }
+  const isBottom = props.controlsPosition === "bottom";
+  return /* @__PURE__ */ jsx(Suspense, { fallback: null, children: /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: `flex ${isBottom ? "flex-col" : "flex-row"} w-full h-full`,
+      style: { height: props.height },
+      children: [
+        /* @__PURE__ */ jsx("div", { className: "flex-1 min-w-0", children: preview }),
+        /* @__PURE__ */ jsx(
+          OrbitalConfigPanel,
+          {
+            schema: parsedSchema,
+            exposedTiers: props.exposedTiers,
+            position: props.controlsPosition,
+            onSchemaChange: setControlledSchema
+          }
+        )
+      ]
+    }
   ) });
-});
+}
 AlmadarApp.displayName = "AlmadarApp";
 
-export { AlmadarApp };
+export { AlmadarApp, OrbitalConfigPanel };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/react/AlmadarApp.tsx"],"names":["AlmadarApp"],"mappings":";;;;;;AAwBA,IAAM,cAAA,GAAiB,KAAK,YAAY;AACtC,EAAA,MAAM,GAAA,GAAM,MAAM,OAAO,qBAAqB,CAAA;AAC9C,EAAA,OAAO,EAAE,OAAA,EAAS,GAAA,CAAI,UAAA,EAAW;AACnC,CAAC,CAAA;AAED,IAAM,qBAAA,GAAwB,KAAK,YAAY;AAC7C,EAAA,MAAM,GAAA,GAAM,MAAM,OAAO,qBAAqB,CAAA;AAC9C,EAAA,OAAO,EAAE,OAAA,EAAS,GAAA,CAAI,iBAAA,EAAkB;AAC1C,CAAC,CAAA;AAEM,IAAM,UAAA,GAAa,UAAA,CAA2C,SAASA,WAAAA,CAC5E,OACA,GAAA,EACA;AACA,EAAA,MAAM,UAAA,GAAa,OAAiE,IAAI,CAAA;AAExF,EAAA,mBAAA,CAAoB,KAAK,OAAO;AAAA,IAC9B,IAAA,CAAK,OAAO,OAAA,EAAS;AACnB,MAAA,IAAI,UAAA,CAAW,YAAY,IAAA,EAAM;AACjC,MAAA,UAAA,CAAW,OAAA,CAAQ,OAAO,OAAO,CAAA;AAAA,IACnC;AAAA,GACF,CAAE,CAAA;AAEF,EAAA,MAAM,IAAA,GAAO,MAAM,IAAA,IAAQ,QAAA;AAE3B,EAAA,uBACE,GAAA,CAAC,QAAA,EAAA,EAAS,QAAA,EAAU,IAAA,EACjB,mBAAS,MAAA,mBACR,GAAA;AAAA,IAAC,qBAAA;AAAA,IAAA;AAAA,MACC,QAAQ,KAAA,CAAM,MAAA;AAAA,MACd,IAAA,EAAK,MAAA;AAAA,MACL,iBAAiB,KAAA,CAAM,eAAA;AAAA,MACvB,QAAQ,KAAA,CAAM,MAAA;AAAA,MACd,WAAW,KAAA,CAAM;AAAA;AAAA,GACnB,mBAEA,GAAA;AAAA,IAAC,cAAA;AAAA,IAAA;AAAA,MACC,QAAQ,KAAA,CAAM,MAAA;AAAA,MACd,UAAU,KAAA,CAAM,IAAA;AAAA,MAChB,WAAW,KAAA,CAAM,SAAA;AAAA,MACjB,iBAAiB,KAAA,CAAM,eAAA;AAAA,MACvB,QAAQ,KAAA,CAAM,MAAA;AAAA,MACd,WAAW,KAAA,CAAM;AAAA;AAAA,GACnB,EAEJ,CAAA;AAEJ,CAAC;AAED,UAAA,CAAW,WAAA,GAAc,YAAA","file":"index.js","sourcesContent":["'use client';\n\n/**\n * `<AlmadarApp />` — renders an orbital schema in the customer's React tree.\n *\n * Thin facade over `@almadar/ui`'s `OrbPreview` (server-backed) and\n * `BrowserPlayground` (in-browser mock server). The `mode` prop picks the\n * runtime path:\n *   - `static`: pure OrbPreview with `mockData`\n *   - `mock`  : BrowserPlayground (in-browser server, faker-seeded)\n *   - `server`: OrbPreview with `serverUrl`\n *\n * Lazy-imports the heavy runtime bundle so the SDK is import-cheap in Next.js\n * server components; the actual render happens client-side under a Suspense\n * boundary. CSS is imported as a side-effect at module load.\n */\n\nimport { lazy, forwardRef, Suspense, useImperativeHandle, useRef } from 'react';\nimport type { EventPayload } from '@almadar/core';\nimport type { AlmadarAppProps, AlmadarAppRef } from '../types';\n// Required global styles. Customers who self-manage Tailwind can import from\n// the (forthcoming) `@almadar/sdk/react/no-css` entry instead.\nimport '@almadar/ui/index.css';\n\nconst OrbPreviewLazy = lazy(async () => {\n  const mod = await import('@almadar/ui/runtime');\n  return { default: mod.OrbPreview };\n});\n\nconst BrowserPlaygroundLazy = lazy(async () => {\n  const mod = await import('@almadar/ui/runtime');\n  return { default: mod.BrowserPlayground };\n});\n\nexport const AlmadarApp = forwardRef<AlmadarAppRef, AlmadarAppProps>(function AlmadarApp(\n  props,\n  ref,\n) {\n  const emitterRef = useRef<((event: string, payload?: EventPayload) => void) | null>(null);\n\n  useImperativeHandle(ref, () => ({\n    emit(event, payload) {\n      if (emitterRef.current === null) return;\n      emitterRef.current(event, payload);\n    },\n  }));\n\n  const mode = props.mode ?? 'static';\n\n  return (\n    <Suspense fallback={null}>\n      {mode === 'mock' ? (\n        <BrowserPlaygroundLazy\n          schema={props.schema}\n          mode=\"mock\"\n          initialPagePath={props.initialPagePath}\n          height={props.height}\n          className={props.className}\n        />\n      ) : (\n        <OrbPreviewLazy\n          schema={props.schema}\n          mockData={props.data}\n          serverUrl={props.serverUrl}\n          initialPagePath={props.initialPagePath}\n          height={props.height}\n          className={props.className}\n        />\n      )}\n    </Suspense>\n  );\n});\n\nAlmadarApp.displayName = 'AlmadarApp';\n"]}
+{"version":3,"sources":["../../src/react/OrbitalConfigPanel.tsx","../../src/react/AlmadarApp.tsx"],"names":["parseSchema","useMemo","useState","jsx","jsxs"],"mappings":"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","file":"index.js","sourcesContent":["'use client';\n\n/**\n * OrbitalConfigPanel — auto-derived control rail for an orbital schema.\n *\n * Finds the first trait that declares a non-empty `config`, filters its fields\n * by the consumer-supplied `exposedTiers`, and renders `@almadar/ui`'s\n * `PropertyInspector`. Every control change deep-clones the schema, writes the\n * new value into the matching field's `default`, and emits the mutated schema\n * so the host can pass it to `OrbPreview`.\n */\n\nimport React, { useMemo, useState } from 'react';\nimport type {\n  ConfigFieldDeclaration,\n  DeclaredTraitConfig,\n  OrbitalSchema,\n  Trait,\n  TraitConfigValue,\n} from '@almadar/core';\nimport { PropertyInspector } from '@almadar/ui/components';\nimport { Stack, Box, Typography } from '@almadar/ui/components';\n\ninterface ConfigTraitTarget {\n  name: string;\n  config: DeclaredTraitConfig;\n}\n\nfunction parseSchema(schema: string | OrbitalSchema): OrbitalSchema {\n  if (typeof schema === 'string') {\n    return JSON.parse(schema) as OrbitalSchema;\n  }\n  return schema;\n}\n\nfunction deepClone<T>(value: T): T {\n  return JSON.parse(JSON.stringify(value)) as T;\n}\n\nfunction findConfigTrait(schema: OrbitalSchema | null): ConfigTraitTarget | null {\n  if (!schema?.orbitals) return null;\n  for (const orbital of schema.orbitals) {\n    for (const traitRef of orbital.traits ?? []) {\n      if (typeof traitRef !== 'object' || traitRef === null) continue;\n      const trait = traitRef as Trait | { ref?: string; config?: DeclaredTraitConfig };\n      if (trait.config && Object.keys(trait.config).length > 0) {\n        const name = 'name' in trait && typeof trait.name === 'string' ? trait.name : 'Config';\n        return { name, config: trait.config };\n      }\n    }\n  }\n  return null;\n}\n\nfunction applyConfigOverride(\n  schema: OrbitalSchema,\n  field: string,\n  value: TraitConfigValue,\n): OrbitalSchema {\n  const next = deepClone(schema);\n  for (const orbital of next.orbitals ?? []) {\n    for (const traitRef of orbital.traits ?? []) {\n      if (typeof traitRef !== 'object' || traitRef === null) continue;\n      const trait = traitRef as { config?: Record<string, ConfigFieldDeclaration> };\n      if (trait.config && field in trait.config) {\n        trait.config[field] = { ...trait.config[field], default: value };\n        return next;\n      }\n    }\n  }\n  return next;\n}\n\nexport interface OrbitalConfigPanelProps {\n  schema: string | OrbitalSchema;\n  exposedTiers?: string[];\n  position?: 'right' | 'bottom';\n  onSchemaChange?: (schema: OrbitalSchema) => void;\n}\n\nexport function OrbitalConfigPanel({\n  schema,\n  exposedTiers,\n  position = 'right',\n  onSchemaChange,\n}: OrbitalConfigPanelProps): React.ReactElement | null {\n  const parsed = useMemo(() => parseSchema(schema), [schema]);\n  const target = useMemo(() => findConfigTrait(parsed), [parsed]);\n  const [values, setValues] = useState<Record<string, TraitConfigValue>>({});\n\n  if (!target) return null;\n\n  const sortedConfig: DeclaredTraitConfig = Object.fromEntries(\n    Object.entries(target.config).sort(([a], [b]) => a.localeCompare(b)),\n  );\n\n  const handleChange = (field: string, value: TraitConfigValue): void => {\n    setValues((prev) => ({ ...prev, [field]: value }));\n    const nextSchema = applyConfigOverride(parsed, field, value);\n    onSchemaChange?.(nextSchema);\n  };\n\n  const handleReset = (): void => {\n    setValues({});\n    onSchemaChange?.(parsed);\n  };\n\n  const isHorizontal = position === 'bottom';\n\n  return (\n    <Box\n      className={`${\n        isHorizontal ? 'w-full border-t' : 'h-full w-80 flex-shrink-0 border-l'\n      } border-border bg-card p-3 overflow-y-auto`}\n    >\n      <Stack direction=\"vertical\" gap=\"sm\">\n        <Typography variant=\"caption\" weight=\"bold\" color=\"muted\">\n          Controls\n        </Typography>\n        <PropertyInspector\n          title={target.name}\n          config={sortedConfig}\n          values={values}\n          onChange={handleChange}\n          onReset={handleReset}\n          tiers={exposedTiers}\n        />\n      </Stack>\n    </Box>\n  );\n}\n\nOrbitalConfigPanel.displayName = 'OrbitalConfigPanel';\n","'use client';\n\n/**\n * `<AlmadarApp />` — renders an orbital schema in the customer's React tree.\n *\n * Thin facade over `@almadar/ui`'s `OrbPreview` (server-backed) and\n * `BrowserPlayground` (in-browser mock server). The `mode` prop picks the\n * runtime path:\n *   - `static`: pure OrbPreview with `mockData`\n *   - `mock`  : BrowserPlayground (in-browser server, faker-seeded)\n *   - `server`: OrbPreview with `serverUrl`\n *\n * Lazy-imports the heavy runtime bundle so the SDK is import-cheap in Next.js\n * server components; the actual render happens client-side under a Suspense\n * boundary. CSS is imported as a side-effect at module load.\n */\n\nimport { lazy, Suspense, useEffect, useMemo, useState } from 'react';\nimport type { AlmadarAppProps } from '../types';\nimport type { OrbitalSchema } from '@almadar/core';\nimport { OrbitalConfigPanel } from './OrbitalConfigPanel';\n// Required global styles. Customers who self-manage Tailwind can import from\n// the (forthcoming) `@almadar/sdk/react/no-css` entry instead.\nimport '@almadar/ui/index.css';\n\nconst OrbPreviewLazy = lazy(async () => {\n  const mod = await import('@almadar/ui/runtime');\n  return { default: mod.OrbPreview };\n});\n\nconst BrowserPlaygroundLazy = lazy(async () => {\n  const mod = await import('@almadar/ui/runtime');\n  return { default: mod.BrowserPlayground };\n});\n\nfunction parseSchema(schema: string | OrbitalSchema): OrbitalSchema {\n  if (typeof schema === 'string') {\n    return JSON.parse(schema) as OrbitalSchema;\n  }\n  return schema;\n}\n\nexport function AlmadarApp(props: AlmadarAppProps) {\n  const mode = props.mode ?? 'static';\n  const parsedSchema = useMemo(() => parseSchema(props.schema), [props.schema]);\n  const [controlledSchema, setControlledSchema] = useState<OrbitalSchema>(parsedSchema);\n\n  // Reset controlled schema when the incoming schema changes.\n  useEffect(() => {\n    setControlledSchema(parsedSchema);\n  }, [parsedSchema]);\n\n  const effectiveSchema = props.exposedTiers && mode !== 'server' ? controlledSchema : parsedSchema;\n  const showControls = props.exposedTiers && props.exposedTiers.length > 0 && mode !== 'server';\n\n  const preview = mode === 'mock' ? (\n    <BrowserPlaygroundLazy\n      schema={effectiveSchema}\n      mode=\"mock\"\n      initialPagePath={props.initialPagePath}\n      height={props.height}\n      className={props.className}\n    />\n  ) : (\n    <OrbPreviewLazy\n      schema={effectiveSchema}\n      mockData={props.data}\n      serverUrl={props.serverUrl}\n      initialPagePath={props.initialPagePath}\n      height={props.height}\n      className={props.className}\n    />\n  );\n\n  if (!showControls) {\n    return (\n      <Suspense fallback={null}>\n        {preview}\n      </Suspense>\n    );\n  }\n\n  const isBottom = props.controlsPosition === 'bottom';\n\n  return (\n    <Suspense fallback={null}>\n      <div\n        className={`flex ${isBottom ? 'flex-col' : 'flex-row'} w-full h-full`}\n        style={{ height: props.height }}\n      >\n        <div className=\"flex-1 min-w-0\">\n          {preview}\n        </div>\n        <OrbitalConfigPanel\n          schema={parsedSchema}\n          exposedTiers={props.exposedTiers}\n          position={props.controlsPosition}\n          onSchemaChange={setControlledSchema}\n        />\n      </div>\n    </Suspense>\n  );\n}\n\nAlmadarApp.displayName = 'AlmadarApp';\n"]}

package/dist/server/express.d.ts

@@ -0,0 +1,39 @@
+import { Request, RequestHandler } from 'express';
+
+/**
+ * `@almadar/sdk/server/express` — Express adapter for the Almadar server handlers.
+ *
+ * Node-only. The consumer must provide their own `express` installation.
+ * This module imports express TYPES only; it is never bundled with express itself.
+ *
+ * Usage:
+ *   import { createGenerateHandler, createEditHandler } from '@almadar/sdk/server/express';
+ *   app.post('/api/agent/generate', createGenerateHandler({ apiKey }));
+ *   app.put('/api/agent/edit', createEditHandler({ apiKey }));
+ */
+
+interface GenerateHandlerOptions {
+    /** API key issued from Studio's /settings/sdk panel. */
+    apiKey: string;
+    /** Defaults to https://studio.almadar.io. */
+    baseUrl?: string;
+    /**
+     * Derive a stable end-user id from the Express request.
+     * Falls back to the `x-user-id` request header when omitted.
+     */
+    endUserId?: (req: Request) => string;
+}
+/**
+ * Returns an Express `RequestHandler` that streams a generate call as SSE.
+ *
+ * Body shape accepted: `{ prompt: string; endUserId?: string; appId?: string }`
+ */
+declare function createGenerateHandler(opts: GenerateHandlerOptions): RequestHandler;
+/**
+ * Returns an Express `RequestHandler` that calls `editSchema` and returns JSON.
+ *
+ * Body shape accepted: `{ appId: string; patch: EditSchemaPatch }`
+ */
+declare function createEditHandler(opts: GenerateHandlerOptions): RequestHandler;
+
+export { type GenerateHandlerOptions, createEditHandler, createGenerateHandler };