@ankhorage/contracts 1.11.0 → 1.13.0

package/src/bindings.ts

@@ -1,4 +1,7 @@
-import type { DbFilter, DbPage, DbSort } from './db';
+import type { DataSourceId, EndpointId, OperationId } from './data';
+
+export type ComponentInstanceId = string;
+export type ComponentTypeId = string;
 
 export type BindingValue =
   | string
@@ -10,45 +13,118 @@ export type BindingValue =
       readonly [key: string]: BindingValue;
     };
 
-export type BindingRefreshMode = 'focus' | 'live' | 'poll' | 'static';
+export type BindingDataPath = string;
+
+export type BindingValueTransform = 'lowercase' | 'trim' | 'uppercase';
 
-export interface DbCollectionQueryBinding {
-  readonly collection: string;
-  readonly schema?: string;
-  readonly columns?: readonly string[];
-  readonly filters?: readonly DbFilter[];
-  readonly sort?: readonly DbSort[];
-  readonly page?: DbPage;
-  readonly refresh?: BindingRefreshMode;
-  readonly pollIntervalMs?: number;
+export interface BindingOperationRef {
+  readonly dataSourceId: DataSourceId;
+  readonly operationId: OperationId;
+  readonly endpointId?: EndpointId;
 }
 
 export type BindingValueSource =
   | {
-      readonly source: 'context';
-      readonly path: string;
+      readonly kind: 'context';
+      readonly path: BindingDataPath;
     }
   | {
-      readonly source: 'db.collection';
-      readonly query: DbCollectionQueryBinding;
+      readonly kind: 'event';
+      readonly path: BindingDataPath;
     }
   | {
-      readonly source: 'event';
-      readonly path: string;
+      readonly kind: 'literal';
+      readonly value: BindingValue;
+    }
+  | {
+      readonly kind: 'operation';
+      readonly operation: BindingOperationRef;
+      readonly path?: BindingDataPath;
+    }
+  | {
+      readonly kind: 'state';
+      readonly path: BindingDataPath;
+    };
+
+export interface BindingValueExpression {
+  readonly source: BindingValueSource;
+  readonly transforms?: readonly BindingValueTransform[];
+}
+
+export interface BindingFallback {
+  readonly value?: BindingValue;
+  readonly source?: BindingValueSource;
+}
+
+export type BindingLifecycleState = 'empty' | 'error' | 'loading';
+
+export interface BindingLifecycleBehavior {
+  readonly state: BindingLifecycleState;
+  readonly fallback?: BindingFallback;
+  readonly message?: string;
+}
+
+export interface PropBinding {
+  readonly source: BindingValueSource;
+  readonly fallback?: BindingFallback;
+  readonly loading?: BindingLifecycleBehavior;
+  readonly error?: BindingLifecycleBehavior;
+  readonly empty?: BindingLifecycleBehavior;
+  readonly transforms?: readonly BindingValueTransform[];
+}
+
+export type BindingInputValue =
+  | {
+      readonly kind: 'array';
+      readonly items: readonly BindingInputValue[];
     }
   | {
-      readonly source: 'literal';
+      readonly kind: 'literal';
       readonly value: BindingValue;
     }
   | {
-      readonly source: 'state';
-      readonly path: string;
+      readonly kind: 'object';
+      readonly fields: Readonly<Record<string, BindingInputValue>>;
+    }
+  | {
+      readonly kind: 'source';
+      readonly source: BindingValueSource;
+      readonly transforms?: readonly BindingValueTransform[];
     };
 
-export type BindingValueTransform = 'lowercase' | 'trim' | 'uppercase';
+export type BindingInputMap = Readonly<Record<string, BindingInputValue>>;
+
+export type BindingConditionOperator = 'eq' | 'exists' | 'neq' | 'notExists';
 
-export interface NodePropBinding {
-  readonly prop: string;
-  readonly valueFrom: BindingValueSource;
-  readonly transform?: BindingValueTransform | readonly BindingValueTransform[];
+export interface BindingCondition {
+  readonly source: BindingValueSource;
+  readonly operator: BindingConditionOperator;
+  readonly value?: BindingValue;
 }
+
+export type EventBindingTarget =
+  | {
+      readonly kind: 'action';
+      readonly type: string;
+    }
+  | {
+      readonly kind: 'operation';
+      readonly operation: BindingOperationRef;
+    };
+
+export interface EventBinding {
+  readonly target: EventBindingTarget;
+  readonly input?: BindingInputMap;
+  readonly when?: BindingCondition;
+}
+
+export interface ComponentDataBinding {
+  readonly componentId: ComponentInstanceId;
+  readonly componentType?: ComponentTypeId;
+  readonly props?: Readonly<Record<string, PropBinding>>;
+  readonly events?: Readonly<Record<string, readonly EventBinding[]>>;
+}
+
+export type ComponentDataBindingRegistry = Readonly<
+  Record<ComponentInstanceId, ComponentDataBinding>
+>;

package/src/contracts.test.ts

@@ -5,8 +5,6 @@ import { COLOR_HARMONIES } from '@ankhorage/color-theory';
 import { describe, expect, it } from 'bun:test';
 
 import {
-  type ActionBinding,
-  type ActionValueSource,
   APP_CATEGORIES,
   type AppCategory,
   AUTH_PROVIDERS,
@@ -21,22 +19,16 @@ import {
   type DbAdapter,
   type DbAdminAdapter,
   type DbChangeEvent,
-  type DbPersistActionBinding,
-  type DbPersistCommand,
   type DbRealtimeAdapter,
   DEPLOYMENT_TARGETS,
-  type EmailSendActionBinding,
   type FormSubmitEventDto,
   type ImageAssetSource,
-  type KnownActionBinding,
-  type KnownCommandDto,
   NAVIGATOR_TYPES,
   type StoragePublicUrlResult,
   type StorageResult,
   type StorageUploadResult,
   type ThemeConfig,
   type ThemeModeConfig,
-  type UiNode,
 } from './index';
 
 async function collectTypeScriptFiles(directory: string): Promise<string[]> {
@@ -236,55 +228,6 @@ describe('contracts', () => {
     expect(JSON.parse(JSON.stringify(source))).toEqual(source);
   });
 
-  it('serializes node event bindings for submit actions', () => {
-    const node: UiNode = {
-      id: 'contact-form',
-      type: 'Form',
-      props: {
-        title: 'Contact us',
-      },
-      events: {
-        submit: [
-          {
-            type: 'email.send',
-            payload: {
-              to: 'info@example.com',
-              subject: 'New contact message',
-              bodyFrom: 'payload.values.message',
-            },
-          },
-          {
-            type: 'db.persist',
-            payload: {
-              collection: 'contact_messages',
-              mode: 'columns',
-            },
-          },
-        ],
-      },
-    };
-
-    expect(JSON.parse(JSON.stringify(node))).toEqual(node);
-    expect(node.events?.submit?.map((action) => action.type)).toEqual(['email.send', 'db.persist']);
-  });
-
-  it('accepts conditional node event bindings', () => {
-    const binding: ActionBinding = {
-      type: 'db.persist',
-      payload: {
-        collection: 'contact_messages',
-      },
-      when: {
-        source: 'event',
-        path: 'payload.values.email',
-        operator: 'exists',
-      },
-    };
-
-    expect(binding.when?.operator).toBe('exists');
-    expect(binding.payload?.collection).toBe('contact_messages');
-  });
-
   it('serializes normalized form submit event DTOs', () => {
     const event: FormSubmitEventDto = {
       type: 'form.submit',
@@ -344,121 +287,6 @@ describe('contracts', () => {
     expect(knownEventType).toBe('form.submit');
   });
 
-  it('serializes provider-neutral value sources for action payloads', () => {
-    const sources: readonly ActionValueSource[] = [
-      { source: 'event', path: 'payload.values.email' },
-      { source: 'literal', value: 'website-contact-form' },
-      { source: 'context', path: 'auth.user.id' },
-      { source: 'state', path: 'forms.contact.isSubmitting' },
-    ];
-
-    expect(JSON.parse(JSON.stringify(sources))).toEqual(sources);
-    expect(sources.map((source) => source.source)).toEqual([
-      'event',
-      'literal',
-      'context',
-      'state',
-    ]);
-  });
-
-  it('serializes a typed db.persist action binding', () => {
-    const binding: DbPersistActionBinding = {
-      type: 'db.persist',
-      payload: {
-        collection: 'contact_messages',
-        mode: 'columns',
-        values: [
-          {
-            field: 'firstname',
-            valueFrom: { source: 'event', path: 'payload.values.firstname' },
-            transform: 'trim',
-          },
-          {
-            field: 'message',
-            valueFrom: { source: 'event', path: 'payload.values.message' },
-          },
-          {
-            field: 'source',
-            valueFrom: { source: 'literal', value: 'website-contact-form' },
-          },
-        ],
-      },
-    };
-
-    expect(JSON.parse(JSON.stringify(binding))).toEqual(binding);
-    expect(binding.payload.values.map((value) => value.field)).toEqual([
-      'firstname',
-      'message',
-      'source',
-    ]);
-  });
-
-  it('serializes a typed email.send action binding', () => {
-    const binding: EmailSendActionBinding = {
-      type: 'email.send',
-      payload: {
-        to: 'info@example.com',
-        subject: 'New contact message',
-        bodyFrom: { source: 'event', path: 'payload.values.message' },
-      },
-    };
-
-    expect(JSON.parse(JSON.stringify(binding))).toEqual(binding);
-    expect(binding.payload.bodyFrom?.source).toBe('event');
-  });
-
-  it('accepts typed action bindings in node event bindings', () => {
-    const persist: DbPersistActionBinding = {
-      type: 'db.persist',
-      payload: {
-        collection: 'contact_messages',
-        values: [
-          {
-            field: 'message',
-            valueFrom: { source: 'event', path: 'payload.values.message' },
-          },
-        ],
-      },
-    };
-    const email: EmailSendActionBinding = {
-      type: 'email.send',
-      payload: {
-        to: 'info@example.com',
-        bodyFrom: { source: 'event', path: 'payload.values.message' },
-      },
-    };
-    const node: UiNode = {
-      id: 'contact-form',
-      type: 'Form',
-      events: {
-        submit: [persist, email],
-      },
-    };
-    const known: KnownActionBinding = persist;
-
-    expect(node.events?.submit?.map((action) => action.type)).toEqual(['db.persist', 'email.send']);
-    expect(known.type).toBe('db.persist');
-  });
-
-  it('serializes a normalized db.persist command DTO', () => {
-    const command: DbPersistCommand = {
-      type: 'db.persist.command',
-      payload: {
-        operation: 'insert',
-        collection: 'contact_messages',
-        mode: 'columns',
-        values: {
-          firstname: 'Fabio',
-          message: 'This is my contact message',
-        },
-      },
-    };
-    const knownCommand: KnownCommandDto = command;
-
-    expect(JSON.parse(JSON.stringify(command))).toEqual(command);
-    expect(knownCommand.type).toBe('db.persist.command');
-  });
-
   it('accepts a provider-neutral CRUD database adapter', async () => {
     const adapter: DbAdapter = {
       capabilities: {

package/src/types.ts

@@ -1,7 +1,8 @@
 import type { ColorHarmony } from '@ankhorage/color-theory';
 
-import type { AuthFlowConfig, AuthIdentifierKind, AuthSignUpField } from './auth';
-import type { NodePropBinding } from './bindings';
+import type { AuthFlowConfig, AuthIdentifierKind, AuthOAuthConfig, AuthSignUpField } from './auth';
+import type { ComponentDataBindingRegistry } from './bindings';
+import type { DataSourceRegistry } from './data';
 
 export interface ThemeModeConfig {
   primaryColor: string;
@@ -89,121 +90,6 @@ export type ManifestValue =
   | readonly ManifestValue[]
   | { readonly [key: string]: ManifestValue };
 
-export type ActionValue = ManifestValue;
-
-export type ActionBindingPayload = Record<string, ActionValue>;
-
-export type ActionConditionSource = 'context' | 'event' | 'state';
-
-export type ActionConditionOperator = 'eq' | 'exists' | 'neq' | 'notExists';
-
-export interface ActionCondition {
-  readonly source: ActionConditionSource;
-  readonly path: string;
-  readonly operator: ActionConditionOperator;
-  readonly value?: ActionValue;
-}
-
-export type ActionValueSource =
-  | {
-      readonly source: 'context';
-      readonly path: string;
-    }
-  | {
-      readonly source: 'event';
-      readonly path: string;
-    }
-  | {
-      readonly source: 'literal';
-      readonly value: ActionValue;
-    }
-  | {
-      readonly source: 'state';
-      readonly path: string;
-    };
-
-export type ActionValueTransform = 'lowercase' | 'trim' | 'uppercase';
-
-export interface ActionValueBinding {
-  readonly valueFrom: ActionValueSource;
-  readonly transform?: ActionValueTransform | readonly ActionValueTransform[];
-}
-
-export interface ActionBinding<
-  TType extends string = string,
-  TPayload extends object = ActionBindingPayload,
-> {
-  readonly type: TType;
-  readonly payload?: TPayload;
-  readonly when?: ActionCondition;
-}
-
-export type DbPersistMode = 'columns' | 'json';
-
-export interface DbPersistFieldBinding {
-  readonly field: string;
-  readonly valueFrom: ActionValueSource;
-  readonly transform?: ActionValueTransform | readonly ActionValueTransform[];
-}
-
-export interface DbPersistActionPayload {
-  readonly collection: string;
-  readonly kind?: string;
-  readonly mode?: DbPersistMode;
-  readonly jsonField?: string;
-  readonly values: readonly DbPersistFieldBinding[];
-}
-
-export interface DbPersistActionBinding extends ActionBinding<
-  'db.persist',
-  DbPersistActionPayload
-> {
-  readonly payload: DbPersistActionPayload;
-}
-
-export interface EmailSendActionPayload {
-  readonly to: string;
-  readonly subject?: string;
-  readonly body?: string;
-  readonly bodyFrom?: ActionValueSource;
-}
-
-export interface EmailSendActionBinding extends ActionBinding<
-  'email.send',
-  EmailSendActionPayload
-> {
-  readonly payload: EmailSendActionPayload;
-}
-
-export type KnownActionBinding = DbPersistActionBinding | EmailSendActionBinding;
-
-export type UiNodeEventBindings = Record<string, readonly ActionBinding<string, object>[]>;
-
-export interface CommandDto<
-  TType extends string = string,
-  TPayload extends object = Record<string, ActionValue>,
-> {
-  readonly type: TType;
-  readonly payload: TPayload;
-}
-
-export type DbPersistOperation = 'insert';
-
-export type DbPersistCommandValues = Record<string, ActionValue>;
-
-export interface DbPersistCommandPayload {
-  readonly operation: DbPersistOperation;
-  readonly collection: string;
-  readonly kind?: string;
-  readonly mode?: DbPersistMode;
-  readonly jsonField?: string;
-  readonly values: DbPersistCommandValues;
-}
-
-export type DbPersistCommand = CommandDto<'db.persist.command', DbPersistCommandPayload>;
-
-export type KnownCommandDto = DbPersistCommand;
-
 export type ComponentEventPayloadValue = ManifestValue;
 
 export interface ComponentEventDto<
@@ -331,10 +217,8 @@ export interface UiNode {
   type: string;
   alias?: string;
   props?: Record<string, unknown>;
-  bindings?: readonly NodePropBinding[];
   children?: UiNode[];
   style?: Record<string, number | string>;
-  events?: UiNodeEventBindings;
 }
 
 export interface ScreenSpec {
@@ -404,6 +288,7 @@ export interface AuthSpec {
   flow?: AuthFlowConfig;
   signIn?: AuthSignInSpec;
   signUp?: AuthSignUpSpec;
+  oauth?: AuthOAuthConfig;
   profile?: AuthProfileSpec;
 }
 
@@ -437,6 +322,8 @@ export interface AppManifest {
   infra: InfraManifest;
   navigator: NavigatorSpec;
   screens: Record<string, ScreenSpec>;
+  dataSources?: DataSourceRegistry;
+  dataBindings?: ComponentDataBindingRegistry;
   settings: {
     apiBaseUrl?: string;
     localization: {