@ankhorage/contracts 7.1.0 → 7.3.0

package/src/appManifest/infra.ts

@@ -0,0 +1,199 @@
+import { AUTH_OAUTH_PROVIDER_IDS } from '../auth';
+import {
+  AUTH_PROFILE_CREATE_STRATEGIES,
+  AUTH_PROFILE_PRIMARY_KEY_STRATEGIES,
+  AUTH_PROFILE_UPDATE_STRATEGIES,
+  AUTH_SCOPES,
+  AUTH_SIGN_IN_IDENTIFIERS,
+  AUTH_SIGN_UP_POLICIES,
+  AUTHZ_ENGINES,
+  AUTHZ_KINDS,
+  DATABASE_TIERS,
+  STATE_PERSISTENCE_MODES,
+  STORAGE_PROVIDERS,
+} from '../types';
+import {
+  isOptionalBoolean,
+  isOptionalString,
+  isRecord,
+  isStringArray,
+  isStringRecord,
+} from './shared';
+
+const AUTH_OAUTH_PROVIDER_SET = new Set<string>(AUTH_OAUTH_PROVIDER_IDS);
+const AUTH_PROFILE_CREATE_STRATEGY_SET = new Set<string>(AUTH_PROFILE_CREATE_STRATEGIES);
+const AUTH_PROFILE_PRIMARY_KEY_STRATEGY_SET = new Set<string>(AUTH_PROFILE_PRIMARY_KEY_STRATEGIES);
+const AUTH_PROFILE_UPDATE_STRATEGY_SET = new Set<string>(AUTH_PROFILE_UPDATE_STRATEGIES);
+const AUTH_SCOPE_SET = new Set<string>(AUTH_SCOPES);
+const AUTH_SIGN_IN_IDENTIFIER_SET = new Set<string>(AUTH_SIGN_IN_IDENTIFIERS);
+const AUTH_SIGN_UP_POLICY_SET = new Set<string>(AUTH_SIGN_UP_POLICIES);
+const AUTHZ_ENGINE_SET = new Set<string>(AUTHZ_ENGINES);
+const AUTHZ_KIND_SET = new Set<string>(AUTHZ_KINDS);
+const DATABASE_TIER_SET = new Set<string>(DATABASE_TIERS);
+const STATE_PERSISTENCE_MODE_SET = new Set<string>(STATE_PERSISTENCE_MODES);
+const STORAGE_PROVIDER_SET = new Set<string>(STORAGE_PROVIDERS);
+
+export function isInfraManifest(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    (value.deployment === undefined || isDeploymentSpec(value.deployment)) &&
+    (value.auth === undefined || isAuthSpec(value.auth)) &&
+    (value.database === undefined || isDatabaseSpec(value.database)) &&
+    (value.storage === undefined || isStorageSpec(value.storage)) &&
+    (value.state === undefined || isStateSpec(value.state)) &&
+    (value.networking === undefined || isNetworkingSpec(value.networking)) &&
+    Array.isArray(value.modules) &&
+    value.modules.every((moduleId) => typeof moduleId === 'string') &&
+    (value.modulesConfig === undefined || isRecord(value.modulesConfig)) &&
+    !('plugins' in value) &&
+    !('pluginsConfig' in value)
+  );
+}
+
+function isDeploymentSpec(value: unknown): boolean {
+  return (
+    isRecord(value) && typeof value.target === 'string' && typeof value.monitoring === 'boolean'
+  );
+}
+
+function isDatabaseSpec(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.provider === 'string' &&
+    typeof value.tier === 'string' &&
+    DATABASE_TIER_SET.has(value.tier)
+  );
+}
+
+function isStorageSpec(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.provider === 'string' &&
+    STORAGE_PROVIDER_SET.has(value.provider) &&
+    isStringArray(value.buckets)
+  );
+}
+
+function isStateSpec(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.provider === 'string' &&
+    (value.persistence === undefined ||
+      (typeof value.persistence === 'string' && STATE_PERSISTENCE_MODE_SET.has(value.persistence)))
+  );
+}
+
+function isNetworkingSpec(value: unknown): boolean {
+  return isRecord(value) && isOptionalString(value.domain) && typeof value.cdn === 'boolean';
+}
+
+function isAuthSpec(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.scope === 'string' &&
+    AUTH_SCOPE_SET.has(value.scope) &&
+    typeof value.provider === 'string' &&
+    (value.authorization === undefined || isAuthzSpec(value.authorization)) &&
+    (value.flow === undefined || isAuthFlow(value.flow)) &&
+    (value.signIn === undefined || isAuthSignInSpec(value.signIn)) &&
+    (value.signUp === undefined || isAuthSignUpSpec(value.signUp)) &&
+    (value.oauth === undefined || isAuthOAuthConfig(value.oauth)) &&
+    (value.profile === undefined || isAuthProfileSpec(value.profile))
+  );
+}
+
+function isAuthzSpec(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.kind === 'string' &&
+    AUTHZ_KIND_SET.has(value.kind) &&
+    typeof value.engine === 'string' &&
+    AUTHZ_ENGINE_SET.has(value.engine)
+  );
+}
+
+function isAuthFlow(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.signInRoute === 'string' &&
+    isOptionalString(value.signUpRoute) &&
+    isOptionalString(value.signOutRoute) &&
+    isOptionalString(value.forgotPasswordRoute) &&
+    isOptionalString(value.otpRoute) &&
+    typeof value.postSignInRoute === 'string' &&
+    isOptionalString(value.unauthorizedRoute)
+  );
+}
+
+function isAuthSignInSpec(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    Array.isArray(value.identifiers) &&
+    value.identifiers.every(
+      (identifier) => typeof identifier === 'string' && AUTH_SIGN_IN_IDENTIFIER_SET.has(identifier),
+    )
+  );
+}
+
+function isAuthSignUpSpec(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    isStringArray(value.requiredFields) &&
+    (value.optionalFields === undefined || isStringArray(value.optionalFields)) &&
+    (value.signUpPolicy === undefined ||
+      (typeof value.signUpPolicy === 'string' && AUTH_SIGN_UP_POLICY_SET.has(value.signUpPolicy)))
+  );
+}
+
+function isAuthOAuthConfig(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.enabled === 'boolean' &&
+    typeof value.callbackRoute === 'string' &&
+    Array.isArray(value.providers) &&
+    value.providers.every(isAuthOAuthProviderConfig)
+  );
+}
+
+function isAuthOAuthProviderConfig(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.id === 'string' &&
+    (AUTH_OAUTH_PROVIDER_SET.has(value.id) || value.id.length > 0) &&
+    isOptionalString(value.label) &&
+    isOptionalBoolean(value.enabled) &&
+    (value.scopes === undefined || isStringArray(value.scopes)) &&
+    (value.queryParams === undefined || isStringRecord(value.queryParams)) &&
+    (value.icon === undefined || isIconSpec(value.icon)) &&
+    (value.credentialsRef === undefined || typeof value.credentialsRef === 'string')
+  );
+}
+
+function isAuthProfileSpec(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    isStringArray(value.fields) &&
+    isOptionalString(value.table) &&
+    (value.primaryKey === undefined ||
+      (typeof value.primaryKey === 'string' &&
+        AUTH_PROFILE_PRIMARY_KEY_STRATEGY_SET.has(value.primaryKey))) &&
+    (value.createStrategy === undefined ||
+      (typeof value.createStrategy === 'string' &&
+        AUTH_PROFILE_CREATE_STRATEGY_SET.has(value.createStrategy))) &&
+    (value.updateStrategy === undefined ||
+      (typeof value.updateStrategy === 'string' &&
+        AUTH_PROFILE_UPDATE_STRATEGY_SET.has(value.updateStrategy)))
+  );
+}
+
+function isIconSpec(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.name === 'string' &&
+    isOptionalString(value.provider) &&
+    (value.size === undefined ||
+      typeof value.size === 'string' ||
+      typeof value.size === 'number') &&
+    isOptionalString(value.color)
+  );
+}

package/src/appManifest/media.ts

@@ -0,0 +1,101 @@
+import {
+  MEDIA_ASSET_KINDS,
+  type MediaAsset,
+  type MediaAssetMetadata,
+  type MediaAssetSource,
+  type MediaManifest,
+} from '../media';
+import { isOptionalString, isRecord } from './shared';
+
+const MEDIA_ASSET_KIND_SET = new Set<string>(MEDIA_ASSET_KINDS);
+
+export function isMediaManifest(value: unknown): value is MediaManifest {
+  if (!isRecord(value) || !hasOnlyKeys(value, ['assets']) || !isRecord(value.assets)) return false;
+
+  return Object.entries(value.assets).every(
+    ([assetId, asset]) => isMediaAsset(asset) && asset.id === assetId,
+  );
+}
+
+function isMediaAsset(value: unknown): value is MediaAsset {
+  return (
+    isRecord(value) &&
+    hasOnlyKeys(value, ['id', 'name', 'kind', 'source', 'contentType', 'metadata']) &&
+    isNonEmptyString(value.id) &&
+    isNonEmptyString(value.name) &&
+    typeof value.kind === 'string' &&
+    MEDIA_ASSET_KIND_SET.has(value.kind) &&
+    isMediaAssetSource(value.source) &&
+    isOptionalString(value.contentType) &&
+    (value.metadata === undefined || isMediaAssetMetadata(value.metadata))
+  );
+}
+
+function isMediaAssetSource(value: unknown): value is MediaAssetSource {
+  if (!isRecord(value) || typeof value.kind !== 'string') return false;
+
+  if (value.kind === 'storage') {
+    return (
+      hasOnlyKeys(value, ['kind', 'storageId', 'bucket', 'path']) &&
+      isOptionalString(value.storageId) &&
+      isNonEmptyString(value.bucket) &&
+      isNonEmptyString(value.path)
+    );
+  }
+
+  if (value.kind === 'url') {
+    return hasOnlyKeys(value, ['kind', 'url']) && isStableRemoteUrl(value.url);
+  }
+
+  return (
+    value.kind === 'bundled' && hasOnlyKeys(value, ['kind', 'path']) && isBundledPath(value.path)
+  );
+}
+
+function isMediaAssetMetadata(value: unknown): value is MediaAssetMetadata {
+  return (
+    isRecord(value) &&
+    hasOnlyKeys(value, [
+      'originalFileName',
+      'sizeBytes',
+      'createdAt',
+      'width',
+      'height',
+      'durationMs',
+    ]) &&
+    isOptionalString(value.originalFileName) &&
+    isOptionalString(value.createdAt) &&
+    isOptionalFiniteNonNegativeNumber(value.sizeBytes) &&
+    isOptionalFinitePositiveNumber(value.width) &&
+    isOptionalFinitePositiveNumber(value.height) &&
+    isOptionalFiniteNonNegativeNumber(value.durationMs)
+  );
+}
+
+function isStableRemoteUrl(value: unknown): boolean {
+  return typeof value === 'string' && /^https?:\/\//iu.test(value.trim());
+}
+
+function isBundledPath(value: unknown): boolean {
+  if (!isNonEmptyString(value)) return false;
+  const path = value.trim();
+  if (path.startsWith('/') || /^[a-z][a-z0-9+.-]*:/iu.test(path)) return false;
+  return !path.split('/').includes('..');
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function isOptionalFiniteNonNegativeNumber(value: unknown): boolean {
+  return value === undefined || (typeof value === 'number' && Number.isFinite(value) && value >= 0);
+}
+
+function isOptionalFinitePositiveNumber(value: unknown): boolean {
+  return value === undefined || (typeof value === 'number' && Number.isFinite(value) && value > 0);
+}
+
+function hasOnlyKeys(value: Record<string, unknown>, allowedKeys: readonly string[]): boolean {
+  const allowed = new Set(allowedKeys);
+  return Object.keys(value).every((key) => allowed.has(key));
+}

package/src/appManifest/screens.ts

@@ -0,0 +1,171 @@
+import { COLOR_HARMONIES } from '@ankhorage/color-theory';
+
+import { APP_CATEGORIES, NAVIGATOR_TYPES } from '../types';
+import { isBindingValueSource, isScreenDataLoaderDefinition } from './bindings';
+import {
+  isOptionalBoolean,
+  isOptionalNumber,
+  isOptionalString,
+  isRecord,
+  isStringArray,
+} from './shared';
+
+const APP_CATEGORY_SET = new Set<string>(APP_CATEGORIES);
+const COLOR_HARMONY_SET = new Set<string>(COLOR_HARMONIES);
+const NAVIGATOR_TYPE_SET = new Set<string>(NAVIGATOR_TYPES);
+const SPLASH_SCREEN_RESIZE_MODE_SET = new Set<string>(['contain', 'cover', 'native']);
+
+export function isManifestMetadata(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.name === 'string' &&
+    typeof value.slug === 'string' &&
+    typeof value.version === 'string' &&
+    typeof value.category === 'string' &&
+    APP_CATEGORY_SET.has(value.category) &&
+    typeof value.themeId === 'string' &&
+    isOptionalString(value.created) &&
+    isOptionalString(value.updated)
+  );
+}
+
+export function isThemeConfig(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.id === 'string' &&
+    typeof value.name === 'string' &&
+    isThemeModeConfig(value.light) &&
+    isThemeModeConfig(value.dark)
+  );
+}
+
+export function isNavigatorSpec(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.type === 'string' &&
+    NAVIGATOR_TYPE_SET.has(value.type) &&
+    isOptionalString(value.initialRouteName) &&
+    Array.isArray(value.routes) &&
+    value.routes.every(isRouteDefinition) &&
+    (value.options === undefined || isRecord(value.options))
+  );
+}
+
+export function isScreenRegistry(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    Object.entries(value).every(
+      ([registryKey, screen]) =>
+        isScreenSpec(screen) && isRecord(screen) && registryKey === screen.id,
+    )
+  );
+}
+
+export function isSplashScreenSpec(value: unknown): boolean {
+  return (
+    isSplashScreenModeSpec(value) &&
+    isRecord(value) &&
+    (value.dark === undefined || isSplashScreenModeSpec(value.dark))
+  );
+}
+
+function isThemeModeConfig(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.primaryColor === 'string' &&
+    typeof value.harmony === 'string' &&
+    COLOR_HARMONY_SET.has(value.harmony)
+  );
+}
+
+function isUiNode(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.id === 'string' &&
+    typeof value.type === 'string' &&
+    isOptionalString(value.alias) &&
+    (value.props === undefined || isRecord(value.props)) &&
+    (value.style === undefined || isRecord(value.style)) &&
+    (value.repeat === undefined || isUiNodeRepeatSpec(value.repeat)) &&
+    (value.children === undefined ||
+      (Array.isArray(value.children) && value.children.every(isUiNode)))
+  );
+}
+
+function isUiNodeRepeatSpec(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    isBindingValueSource(value.source) &&
+    isOptionalString(value.itemAlias) &&
+    isOptionalString(value.keyPath) &&
+    (value.empty === undefined || (Array.isArray(value.empty) && value.empty.every(isUiNode)))
+  );
+}
+
+function isScreenSpec(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.id === 'string' &&
+    typeof value.name === 'string' &&
+    isOptionalString(value.title) &&
+    isOptionalString(value.description) &&
+    (value.dataLoaders === undefined ||
+      (Array.isArray(value.dataLoaders) &&
+        value.dataLoaders.every(isScreenDataLoaderDefinition))) &&
+    (value.requires === undefined || isScreenRequirements(value.requires)) &&
+    isUiNode(value.root)
+  );
+}
+
+function isRouteDefinition(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.name === 'string' &&
+    isOptionalString(value.path) &&
+    isOptionalString(value.label) &&
+    (value.icon === undefined || isIconSpec(value.icon)) &&
+    isOptionalBoolean(value.showInPrimaryNavigation) &&
+    (value.guards === undefined || isStringArray(value.guards)) &&
+    isOptionalString(value.screenId) &&
+    (value.navigator === undefined || isNavigatorSpec(value.navigator))
+  );
+}
+
+function isIconSpec(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    typeof value.name === 'string' &&
+    isOptionalString(value.provider) &&
+    (value.size === undefined ||
+      typeof value.size === 'string' ||
+      typeof value.size === 'number') &&
+    isOptionalString(value.color)
+  );
+}
+
+function isSplashScreenModeSpec(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    isOptionalString(value.image) &&
+    isOptionalNumber(value.imageWidth) &&
+    (value.resizeMode === undefined ||
+      (typeof value.resizeMode === 'string' &&
+        SPLASH_SCREEN_RESIZE_MODE_SET.has(value.resizeMode))) &&
+    isOptionalString(value.backgroundColor)
+  );
+}
+
+function isScreenRequirements(value: unknown): boolean {
+  return (
+    isRecord(value) &&
+    (value.permissions === undefined || isRequirementArray(value.permissions, 'permission')) &&
+    (value.capabilities === undefined || isRequirementArray(value.capabilities, 'capability'))
+  );
+}
+
+function isRequirementArray(value: unknown, key: 'capability' | 'permission'): boolean {
+  return (
+    Array.isArray(value) &&
+    value.every((entry) => isRecord(entry) && typeof entry[key] === 'string')
+  );
+}

package/src/appManifest/shared.ts

@@ -0,0 +1,40 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function isOptionalString(value: unknown): boolean {
+  return value === undefined || typeof value === 'string';
+}
+
+export function isOptionalNumber(value: unknown): boolean {
+  return value === undefined || typeof value === 'number';
+}
+
+export function isOptionalBoolean(value: unknown): boolean {
+  return value === undefined || typeof value === 'boolean';
+}
+
+export function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((entry) => typeof entry === 'string');
+}
+
+export function isStringRecord(value: unknown): boolean {
+  return isRecord(value) && Object.values(value).every((entry) => typeof entry === 'string');
+}
+
+export function isManifestValue(value: unknown): boolean {
+  if (
+    value === null ||
+    typeof value === 'string' ||
+    typeof value === 'number' ||
+    typeof value === 'boolean'
+  ) {
+    return true;
+  }
+
+  if (Array.isArray(value)) {
+    return value.every(isManifestValue);
+  }
+
+  return isRecord(value) && Object.values(value).every(isManifestValue);
+}