@proulr/sdui-contract 0.1.0

package/README.md

@@ -0,0 +1,16 @@
+# proulr-sdui-contract
+
+Contrato SDUI compartilhado (wire snake_case + domínio camelCase).
+
+## Setup
+
+```bash
+npm install
+npm run typecheck
+```
+
+## Consumidores
+
+- `@proulr/sdui-components` — codec + types
+- BFFs — wire payload
+- `proulr-app` — decode no fetch

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@proulr/sdui-contract",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "src"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/saviorbp/proulr-sdui-contract.git"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run typecheck"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './sdui-contract-types';
+export * from './sdui-screen-codec';

package/src/sdui-contract-types.ts

@@ -0,0 +1,186 @@
+/** SDUI screen contract: wire (snake_case) and domain (camelCase). */
+
+export const SDUI_MIN_SCHEMA_VERSION = 1;
+export const SDUI_MAX_SCHEMA_VERSION = 1;
+
+export type SduiOfflinePolicy = 'cache_only' | 'fail' | 'queue';
+
+export type SduiActionType =
+  | 'navigate'
+  | 'open_sheet'
+  | 'api_call'
+  | 'track'
+  | 'toggle_search'
+  | 'refresh_screen'
+  | 'sign_out'
+  | 'noop';
+
+export type SduiBlockWire = {
+  id: string;
+  type: string;
+  props?: Record<string, unknown>;
+  children?: SduiBlockWire[];
+};
+
+export type SduiHeaderWire = {
+  title?: string;
+  subtitle?: string;
+  brand?: boolean;
+  show_back?: boolean;
+  hidden?: boolean;
+  slot_blocks?: SduiBlockWire[];
+  header_search?: { kind: 'vibes' | 'messages' };
+};
+
+export type SduiActionWire = {
+  type: SduiActionType;
+  route?: string;
+  params?: Record<string, string>;
+  sheet_id?: string;
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  path?: string;
+  body?: Record<string, unknown>;
+  event_name?: string;
+  event_props?: Record<string, unknown>;
+};
+
+export type SduiScreenMetaWire = {
+  cache_ttl_ms?: number;
+  offline_policy?: SduiOfflinePolicy;
+  bff?: string;
+};
+
+export type SduiScreenWire = {
+  schema_version: number;
+  screen_id: string;
+  header?: SduiHeaderWire;
+  blocks: SduiBlockWire[];
+  data?: Record<string, unknown>;
+  actions?: Record<string, SduiActionWire>;
+  meta?: SduiScreenMetaWire;
+};
+
+export type SduiBlock = {
+  id: string;
+  type: string;
+  props: Record<string, unknown>;
+  children: SduiBlock[];
+};
+
+export type SduiHeader = {
+  title?: string;
+  subtitle?: string;
+  brand?: boolean;
+  showBack?: boolean;
+  hidden?: boolean;
+  slotBlocks: SduiBlock[];
+  headerSearch?: { kind: 'vibes' | 'messages' };
+};
+
+export type SduiAction = {
+  type: SduiActionType;
+  route?: string;
+  params?: Record<string, string>;
+  sheetId?: string;
+  method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  path?: string;
+  body?: Record<string, unknown>;
+  eventName?: string;
+  eventProps?: Record<string, unknown>;
+};
+
+export type SduiScreenMeta = {
+  cacheTtlMs: number;
+  offlinePolicy: SduiOfflinePolicy;
+  bff?: string;
+};
+
+export type SduiScreen = {
+  schemaVersion: number;
+  screenId: string;
+  header?: SduiHeader;
+  blocks: SduiBlock[];
+  data: Record<string, unknown>;
+  actions: Record<string, SduiAction>;
+  meta: SduiScreenMeta;
+};
+
+export type SduiScreenFetchParams = {
+  screenId: string;
+  routeParams?: Record<string, string>;
+  context?: Record<string, unknown>;
+};
+
+export type SduiScreenMode = 'legacy' | 'hybrid' | 'sdui';
+
+export type SduiScreenBuilderContext = {
+  routeParams?: Record<string, string>;
+  query?: Record<string, string>;
+  authToken?: string;
+};
+
+export type SduiScreenBuilder = (
+  ctx: SduiScreenBuilderContext,
+) => SduiScreenWire | Promise<SduiScreenWire>;
+
+// ─── Style tokens (BFF customization via wire) ────────────────────────────
+
+export type ColorToken =
+  | 'primary'
+  | 'onPrimary'
+  | 'primaryContainer'
+  | 'secondary'
+  | 'onSecondary'
+  | 'secondaryContainer'
+  | 'tertiary'
+  | 'surface'
+  | 'onSurface'
+  | 'onSurfaceVariant'
+  | 'surfaceContainer'
+  | 'surfaceContainerHigh'
+  | 'surfaceContainerHighest'
+  | 'outline'
+  | 'error'
+  | 'onError';
+
+export type SpacingToken = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'xxl';
+
+export type ShapeToken =
+  | 'cornerExtraSmall'
+  | 'cornerSmall'
+  | 'cornerMedium'
+  | 'cornerLarge'
+  | 'cornerExtraLarge'
+  | 'cornerFull';
+
+export type TypeToken =
+  | 'display'
+  | 'headline'
+  | 'title'
+  | 'titleSmall'
+  | 'body'
+  | 'bodySmall'
+  | 'label'
+  | 'labelSmall';
+
+export type StyleWire = {
+  background_color?: ColorToken;
+  color?: ColorToken;
+  padding?: SpacingToken | number;
+  padding_horizontal?: SpacingToken | number;
+  padding_vertical?: SpacingToken | number;
+  margin_top?: SpacingToken | number;
+  gap?: SpacingToken | number;
+  border_radius?: ShapeToken | number;
+  border_width?: number;
+  border_color?: ColorToken;
+  opacity?: number;
+  flex?: number;
+  align_items?: 'flex-start' | 'center' | 'flex-end';
+  typography?: TypeToken;
+};
+
+export type StyleProps = {
+  variant?: string;
+  style?: StyleWire;
+};

package/src/sdui-screen-codec.ts

@@ -0,0 +1,132 @@
+import {
+  SDUI_MAX_SCHEMA_VERSION,
+  SDUI_MIN_SCHEMA_VERSION,
+  type SduiAction,
+  type SduiActionWire,
+  type SduiBlock,
+  type SduiBlockWire,
+  type SduiHeader,
+  type SduiHeaderWire,
+  type SduiOfflinePolicy,
+  type SduiScreen,
+  type SduiScreenMeta,
+  type SduiScreenMetaWire,
+  type SduiScreenWire,
+} from './sdui-contract-types';
+
+const DEFAULT_CACHE_TTL_MS = 30_000;
+const DEFAULT_OFFLINE_POLICY: SduiOfflinePolicy = 'cache_only';
+
+export class SduiCodecError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SduiCodecError';
+  }
+}
+
+function mapBlockWire(wire: SduiBlockWire): SduiBlock {
+  return {
+    id: wire.id,
+    type: wire.type,
+    props: wire.props ?? {},
+    children: (wire.children ?? []).map(mapBlockWire),
+  };
+}
+
+function mapActionWire(wire: SduiActionWire): SduiAction {
+  return {
+    type: wire.type,
+    route: wire.route,
+    params: wire.params,
+    sheetId: wire.sheet_id,
+    method: wire.method,
+    path: wire.path,
+    body: wire.body,
+    eventName: wire.event_name,
+    eventProps: wire.event_props,
+  };
+}
+
+function mapHeaderWire(wire: SduiHeaderWire): SduiHeader {
+  return {
+    title: wire.title,
+    subtitle: wire.subtitle,
+    brand: wire.brand,
+    showBack: wire.show_back,
+    hidden: wire.hidden,
+    slotBlocks: (wire.slot_blocks ?? []).map(mapBlockWire),
+    headerSearch: wire.header_search,
+  };
+}
+
+function mapMetaWire(wire: SduiScreenMetaWire | undefined): SduiScreenMeta {
+  return {
+    cacheTtlMs: wire?.cache_ttl_ms ?? DEFAULT_CACHE_TTL_MS,
+    offlinePolicy: wire?.offline_policy ?? DEFAULT_OFFLINE_POLICY,
+    bff: wire?.bff,
+  };
+}
+
+export function decodeSduiScreenWire(wire: unknown): SduiScreen {
+  if (!wire || typeof wire !== 'object') {
+    throw new SduiCodecError('screen payload must be an object');
+  }
+
+  const payload = wire as SduiScreenWire;
+
+  if (typeof payload.schema_version !== 'number') {
+    throw new SduiCodecError('schema_version is required');
+  }
+
+  if (
+    payload.schema_version < SDUI_MIN_SCHEMA_VERSION ||
+    payload.schema_version > SDUI_MAX_SCHEMA_VERSION
+  ) {
+    throw new SduiCodecError(
+      `unsupported schema_version ${payload.schema_version} (supported ${SDUI_MIN_SCHEMA_VERSION}-${SDUI_MAX_SCHEMA_VERSION})`,
+    );
+  }
+
+  if (typeof payload.screen_id !== 'string' || !payload.screen_id) {
+    throw new SduiCodecError('screen_id is required');
+  }
+
+  if (!Array.isArray(payload.blocks)) {
+    throw new SduiCodecError('blocks must be an array');
+  }
+
+  return {
+    schemaVersion: payload.schema_version,
+    screenId: payload.screen_id,
+    header: payload.header ? mapHeaderWire(payload.header) : undefined,
+    blocks: payload.blocks.map(mapBlockWire),
+    data: payload.data ?? {},
+    actions: Object.fromEntries(
+      Object.entries(payload.actions ?? {}).map(([key, action]) => [key, mapActionWire(action)]),
+    ),
+    meta: mapMetaWire(payload.meta),
+  };
+}
+
+export function createScreenWire(
+  screenId: string,
+  blocks: SduiBlockWire[],
+  options?: {
+    header?: SduiHeaderWire;
+    data?: Record<string, unknown>;
+    actions?: Record<string, SduiActionWire>;
+    meta?: SduiScreenMetaWire;
+  },
+): SduiScreenWire {
+  return {
+    schema_version: 1,
+    screen_id: screenId,
+    header: options?.header,
+    blocks,
+    data: options?.data,
+    actions: options?.actions,
+    meta: options?.meta,
+  };
+}
+
+export * from './sdui-contract-types';