@ankhorage/contracts 1.11.0 → 1.13.0

package/src/auth-oauth.test.ts

@@ -0,0 +1,103 @@
+import { describe, expect, it } from 'bun:test';
+
+import {
+  AUTH_OAUTH_PROVIDER_IDS,
+  type AuthAdapter,
+  type AuthOAuthConfig,
+  type AuthSpec,
+} from './index';
+
+describe('OAuth auth contracts', () => {
+  it('accepts provider-neutral OAuth provider config on auth specs', () => {
+    const oauth: AuthOAuthConfig = {
+      enabled: true,
+      callbackRoute: '/auth/callback',
+      providers: [
+        {
+          id: 'google',
+          label: 'Google',
+          enabled: true,
+          scopes: ['openid', 'email', 'profile'],
+          icon: {
+            provider: 'FontAwesome',
+            name: 'google',
+          },
+        },
+        {
+          id: 'custom-sso',
+          label: 'Custom SSO',
+          enabled: false,
+          redirectTo: '/auth/custom/callback',
+          queryParams: {
+            prompt: 'select_account',
+          },
+        },
+      ],
+    };
+
+    const auth: AuthSpec = {
+      scope: 'global',
+      provider: 'supabase',
+      authorization: { kind: 'RBAC', engine: 'native' },
+      oauth,
+    };
+
+    expect(AUTH_OAUTH_PROVIDER_IDS.includes('google')).toBe(true);
+    expect(auth.oauth?.providers[0]?.icon?.name).toBe('google');
+    expect(auth.oauth?.providers[1]?.id).toBe('custom-sso');
+    expect(auth.oauth?.providers[1]?.enabled).toBe(false);
+  });
+
+  it('accepts optional OAuth adapter capabilities and redirect flow methods', async () => {
+    const adapter: AuthAdapter = {
+      capabilities: {
+        signInIdentifiers: ['email'],
+        supportsSignUp: true,
+        supportsPasswordReset: true,
+        supportsOtp: true,
+        supportsSessionRefresh: true,
+        supportsOAuth: true,
+        oauthProviders: ['google', 'custom-sso'],
+      },
+      signIn() {
+        return Promise.resolve({
+          ok: false,
+          error: { code: 'unsupported', message: 'Password sign-in is not implemented.' },
+        });
+      },
+      signUp() {
+        return Promise.resolve({
+          ok: false,
+          error: { code: 'unsupported', message: 'Sign-up is not implemented.' },
+        });
+      },
+      signOut() {
+        return Promise.resolve({ ok: true });
+      },
+      getSession() {
+        return Promise.resolve({ ok: true, data: null });
+      },
+      signInWithOAuth(input) {
+        return Promise.resolve({
+          ok: true,
+          data: {
+            provider: input.provider,
+            url: `https://auth.example.com/oauth/${input.provider}`,
+          },
+        });
+      },
+    };
+
+    const result = await adapter.signInWithOAuth?.({
+      provider: 'google',
+      redirectTo: '/auth/callback',
+      scopes: ['openid', 'email', 'profile'],
+    });
+
+    expect(adapter.capabilities?.supportsOAuth).toBe(true);
+    expect(adapter.capabilities?.oauthProviders).toEqual(['google', 'custom-sso']);
+    expect(result?.ok).toBe(true);
+    expect(result?.ok === true ? result.data?.provider : undefined).toBe('google');
+    expect(result?.ok === true ? result.data?.url : undefined).toContain('/oauth/google');
+  });
+});

package/src/auth.ts

@@ -1,3 +1,5 @@
+import type { IconSpec } from './types';
+
 export const AUTH_IDENTIFIER_KINDS = ['email', 'phone', 'username'] as const;
 export type AuthIdentifierKind = (typeof AUTH_IDENTIFIER_KINDS)[number];
 
@@ -11,6 +13,30 @@ export const AUTH_SIGN_UP_FIELDS = [
 export type KnownAuthSignUpField = (typeof AUTH_SIGN_UP_FIELDS)[number];
 export type AuthSignUpField = KnownAuthSignUpField | (string & {});
 
+export const AUTH_OAUTH_PROVIDER_IDS = [
+  'apple',
+  'azure',
+  'bitbucket',
+  'discord',
+  'facebook',
+  'figma',
+  'github',
+  'gitlab',
+  'google',
+  'kakao',
+  'keycloak',
+  'linkedin',
+  'notion',
+  'slack',
+  'spotify',
+  'twitch',
+  'twitter',
+  'workos',
+  'zoom',
+] as const;
+export type KnownAuthOAuthProviderId = (typeof AUTH_OAUTH_PROVIDER_IDS)[number];
+export type AuthOAuthProviderId = KnownAuthOAuthProviderId | (string & {});
+
 export interface AuthIdentifier {
   kind: AuthIdentifierKind;
   value: string;
@@ -35,11 +61,28 @@ export interface AuthSignUpConfig {
   optionalFields?: AuthSignUpField[];
 }
 
+export interface AuthOAuthProviderConfig {
+  id: AuthOAuthProviderId;
+  label?: string;
+  enabled?: boolean;
+  scopes?: string[];
+  redirectTo?: string;
+  queryParams?: Record<string, string>;
+  icon?: IconSpec;
+}
+
+export interface AuthOAuthConfig {
+  enabled: boolean;
+  callbackRoute: string;
+  providers: AuthOAuthProviderConfig[];
+}
+
 export interface AuthProviderConfig {
   provider: string;
   flow: AuthFlowConfig;
   signIn: AuthSignInConfig;
   signUp?: AuthSignUpConfig;
+  oauth?: AuthOAuthConfig;
   passwordReset?: {
     enabled: boolean;
   };
@@ -114,12 +157,32 @@ export interface VerifyOtpInput {
   metadata?: Record<string, unknown>;
 }
 
+export interface SignInWithOAuthInput {
+  provider: AuthOAuthProviderId;
+  redirectTo?: string;
+  scopes?: string[];
+  queryParams?: Record<string, string>;
+  metadata?: Record<string, unknown>;
+}
+
+export interface AuthOAuthRedirect {
+  provider: AuthOAuthProviderId;
+  url: string;
+}
+
+export interface CompleteOAuthSignInInput {
+  url: string;
+  redirectTo?: string;
+}
+
 export interface AuthAdapterCapabilities {
   signInIdentifiers: AuthIdentifierKind[];
   supportsSignUp: boolean;
   supportsPasswordReset: boolean;
   supportsOtp: boolean;
   supportsSessionRefresh: boolean;
+  supportsOAuth?: boolean;
+  oauthProviders?: AuthOAuthProviderId[];
 }
 
 export interface AuthAdapter {
@@ -134,4 +197,7 @@ export interface AuthAdapter {
 
   requestPasswordReset?(input: PasswordResetInput): Promise<AuthResult>;
   verifyOtp?(input: VerifyOtpInput): Promise<AuthResult<AuthSession>>;
+
+  signInWithOAuth?(input: SignInWithOAuthInput): Promise<AuthResult<AuthOAuthRedirect>>;
+  completeOAuthSignIn?(input: CompleteOAuthSignInInput): Promise<AuthResult<AuthSession>>;
 }

package/src/bindings.test.ts

@@ -1,96 +1,316 @@
 import { describe, expect, it } from 'bun:test';
 
 import type {
+  AppManifest,
+  BindingInputMap,
   BindingValueSource,
-  DbCollectionQueryBinding,
-  NodePropBinding,
-  UiNode,
+  ComponentDataBinding,
+  ComponentDataBindingRegistry,
+  EventBinding,
+  PropBinding,
 } from './index';
 
-describe('binding contracts', () => {
-  it('serializes a node prop bound to state', () => {
-    const binding: NodePropBinding = {
-      prop: 'value',
-      valueFrom: {
-        source: 'state',
-        path: 'forms.contact.values.firstname',
-      },
-      transform: 'trim',
-    };
-    const node: UiNode = {
-      id: 'firstname-input',
-      type: 'Input',
+function assertSerializable<TValue>(value: TValue): void {
+  expect(JSON.parse(JSON.stringify(value))).toEqual(value);
+}
+
+describe('component data-binding contracts', () => {
+  it('serializes a component prop bound to an operation response path', () => {
+    const binding: ComponentDataBinding = {
+      componentId: 'hero-title',
+      componentType: 'Text',
       props: {
-        label: 'Firstname',
+        children: {
+          source: {
+            kind: 'operation',
+            operation: {
+              dataSourceId: 'cms',
+              endpointId: 'pages',
+              operationId: 'pages.getHome',
+            },
+            path: '$.data.title',
+          },
+          fallback: {
+            value: 'Untitled',
+          },
+          loading: {
+            state: 'loading',
+            fallback: {
+              value: 'Loading…',
+            },
+          },
+          error: {
+            state: 'error',
+            message: 'Could not load title.',
+            fallback: {
+              value: 'Untitled',
+            },
+          },
+          transforms: ['trim'],
+        },
       },
-      bindings: [binding],
     };
 
-    expect(JSON.parse(JSON.stringify(node))).toEqual(node);
-    expect(node.bindings?.[0]?.valueFrom.source).toBe('state');
+    assertSerializable(binding);
+    expect(binding.props?.children?.source.kind).toBe('operation');
   });
 
-  it('serializes a node prop bound to a DB collection query', () => {
-    const query: DbCollectionQueryBinding = {
-      collection: 'posts',
-      schema: 'public',
-      columns: ['id', 'title', 'published'],
-      filters: [{ field: 'published', operator: 'eq', value: true }],
-      sort: [{ field: 'created_at', direction: 'desc' }],
-      page: { limit: 10, offset: 0 },
-      refresh: 'live',
-    };
-    const node: UiNode = {
-      id: 'posts-list',
-      type: 'CollectionList',
-      bindings: [
-        {
-          prop: 'items',
-          valueFrom: {
-            source: 'db.collection',
-            query,
+  it('serializes literal, context, event, state, and operation value sources', () => {
+    const sources: readonly BindingValueSource[] = [
+      { kind: 'literal', value: { fallback: 'Untitled' } },
+      { kind: 'context', path: 'auth.user.displayName' },
+      { kind: 'event', path: 'payload.values.search' },
+      { kind: 'state', path: 'forms.search.query' },
+      {
+        kind: 'operation',
+        operation: {
+          dataSourceId: 'search-api',
+          operationId: 'search.query',
+        },
+        path: '$.results',
+      },
+    ];
+
+    assertSerializable(sources);
+    expect(sources.map((source) => source.kind)).toEqual([
+      'literal',
+      'context',
+      'event',
+      'state',
+      'operation',
+    ]);
+  });
+
+  it('serializes an event binding that executes a data-source operation', () => {
+    const input: BindingInputMap = {
+      email: {
+        kind: 'source',
+        source: {
+          kind: 'event',
+          path: 'payload.values.email',
+        },
+        transforms: ['trim', 'lowercase'],
+      },
+      message: {
+        kind: 'source',
+        source: {
+          kind: 'event',
+          path: 'payload.values.message',
+        },
+      },
+      source: {
+        kind: 'literal',
+        value: 'contact-form',
+      },
+      metadata: {
+        kind: 'object',
+        fields: {
+          userId: {
+            kind: 'source',
+            source: {
+              kind: 'context',
+              path: 'auth.user.id',
+            },
           },
         },
-      ],
+      },
+    };
+
+    const binding: EventBinding = {
+      target: {
+        kind: 'operation',
+        operation: {
+          dataSourceId: 'contact-api',
+          endpointId: 'messages',
+          operationId: 'messages.create',
+        },
+      },
+      input,
+      when: {
+        source: {
+          kind: 'event',
+          path: 'payload.values.email',
+        },
+        operator: 'exists',
+      },
     };
 
-    expect(JSON.parse(JSON.stringify(node))).toEqual(node);
-    expect(node.bindings?.[0]?.valueFrom.source).toBe('db.collection');
+    assertSerializable(binding);
+    expect(binding.target.kind).toBe('operation');
+    expect(binding.input?.email?.kind).toBe('source');
   });
 
-  it('supports literal, context, and event value sources', () => {
-    const sources: readonly BindingValueSource[] = [
-      { source: 'literal', value: { fallback: 'Untitled' } },
-      { source: 'context', path: 'auth.user.displayName' },
-      { source: 'event', path: 'payload.values.search' },
-    ];
+  it('serializes an event binding that targets a named action', () => {
+    const binding: EventBinding = {
+      target: {
+        kind: 'action',
+        type: 'toast.show',
+      },
+      input: {
+        message: {
+          kind: 'literal',
+          value: 'Saved successfully.',
+        },
+      },
+    };
 
-    expect(JSON.parse(JSON.stringify(sources))).toEqual(sources);
-    expect(sources.map((source) => source.source)).toEqual(['literal', 'context', 'event']);
+    assertSerializable(binding);
+    expect(binding.target.kind).toBe('action');
   });
 
-  it('supports static, focus, poll, and live refresh intent', () => {
-    const refreshModes = ['static', 'focus', 'poll', 'live'] as const;
-    const bindings = refreshModes.map(
-      (refresh): NodePropBinding => ({
-        prop: `items.${refresh}`,
-        valueFrom: {
-          source: 'db.collection',
-          query: {
-            collection: 'posts',
-            refresh,
-            pollIntervalMs: refresh === 'poll' ? 30_000 : undefined,
+  it('serializes component data-binding registries', () => {
+    const bindings: ComponentDataBindingRegistry = {
+      'submit-button': {
+        componentId: 'submit-button',
+        componentType: 'Button',
+        props: {
+          children: {
+            source: {
+              kind: 'literal',
+              value: 'Send',
+            },
+          },
+          disabled: {
+            source: {
+              kind: 'state',
+              path: 'forms.contact.isSubmitting',
+            },
           },
         },
-      }),
-    );
+        events: {
+          press: [
+            {
+              target: {
+                kind: 'operation',
+                operation: {
+                  dataSourceId: 'contact-api',
+                  operationId: 'messages.create',
+                },
+              },
+            },
+          ],
+        },
+      },
+    };
 
-    expect(JSON.parse(JSON.stringify(bindings))).toEqual(bindings);
-    expect(bindings.map((binding) => binding.valueFrom.source)).toEqual([
-      'db.collection',
-      'db.collection',
-      'db.collection',
-      'db.collection',
-    ]);
+    assertSerializable(bindings);
+    expect(bindings['submit-button']?.events?.press?.[0]?.target.kind).toBe('operation');
+  });
+
+  it('serializes app-level dataSources and dataBindings on the manifest', () => {
+    const propBinding: PropBinding = {
+      source: {
+        kind: 'operation',
+        operation: {
+          dataSourceId: 'cms',
+          endpointId: 'pages',
+          operationId: 'pages.getHome',
+        },
+        path: '$.data.heroTitle',
+      },
+    };
+
+    const manifest: AppManifest = {
+      metadata: {
+        name: 'Demo',
+        slug: 'demo',
+        version: '1.0.0',
+        themeId: 'default',
+      },
+      themes: [
+        {
+          id: 'default',
+          name: 'Default',
+          light: {
+            primaryColor: '#3366ff',
+            harmony: 'analogous',
+          },
+          dark: {
+            primaryColor: '#3366ff',
+            harmony: 'analogous',
+          },
+        },
+      ],
+      activeThemeId: 'default',
+      infra: {
+        plugins: [],
+      },
+      navigator: {
+        type: 'stack',
+        routes: [
+          {
+            name: 'home',
+            screenId: 'home',
+          },
+        ],
+      },
+      screens: {
+        home: {
+          id: 'home',
+          name: 'Home',
+          root: {
+            id: 'screen-root',
+            type: 'Screen',
+            children: [
+              {
+                id: 'hero-title',
+                type: 'Text',
+              },
+            ],
+          },
+        },
+      },
+      dataSources: {
+        cms: {
+          id: 'cms',
+          kind: 'rest',
+          baseUrl: 'https://cms.example.com',
+          endpoints: {
+            pages: {
+              id: 'pages',
+              kind: 'http',
+              path: '/pages/home',
+              operations: {
+                'pages.getHome': {
+                  id: 'pages.getHome',
+                  endpointId: 'pages',
+                  protocol: 'http',
+                  intent: 'read',
+                  method: 'GET',
+                  path: '/pages/home',
+                },
+              },
+            },
+          },
+        },
+      },
+      dataBindings: {
+        'hero-title': {
+          componentId: 'hero-title',
+          componentType: 'Text',
+          props: {
+            children: propBinding,
+          },
+        },
+      },
+      settings: {
+        localization: {
+          defaultLocale: 'en',
+          locales: ['en'],
+        },
+        authFlow: {
+          signInRoute: '/sign-in',
+          signUpRoute: '/sign-up',
+          signOutRoute: '/sign-out',
+          forgotPasswordRoute: '/forgot-password',
+          postSignInRoute: '/',
+          unauthorizedRoute: '/sign-in',
+        },
+      },
+    };
+
+    assertSerializable(manifest);
+    expect(manifest.dataBindings?.['hero-title']?.props?.children?.source.kind).toBe('operation');
+    expect(manifest.dataSources?.cms?.kind).toBe('rest');
   });
 });