@ankhorage/contracts 19.0.0 → 19.2.0

package/src/types/deployProvider.ts

@@ -0,0 +1,338 @@
+import type { AppDeployTargetId } from '../deploy';
+import type { DeploymentMonetizationAdapter } from './deployMonetization';
+import type { DeploymentReleaseAdapter } from './deployRelease';
+import type { DeploymentStoreListingAdapter } from './deployStoreListing';
+
+export const DEPLOYMENT_CAPABILITIES = [
+  'provision',
+  'prepare',
+  'build',
+  'publish',
+  'verify',
+] as const;
+
+export type DeploymentCapability = (typeof DEPLOYMENT_CAPABILITIES)[number];
+
+export const DEPLOYMENT_PROVIDER_CAPABILITY_IDS = [
+  'setup',
+  'web-publish',
+  'android-build',
+  'android-publish',
+  'ios-build',
+  'ios-publish',
+  'store-listing',
+  'monetization',
+  'release',
+] as const;
+
+export type DeploymentProviderCapabilityId = (typeof DEPLOYMENT_PROVIDER_CAPABILITY_IDS)[number];
+
+export interface DeploymentProviderCapabilityDescriptor {
+  readonly id: DeploymentProviderCapabilityId;
+  readonly targets: readonly AppDeployTargetId[];
+}
+
+export interface DeploymentProviderDescriptor {
+  readonly id: string;
+  readonly packageName: string;
+  readonly displayName: string;
+  readonly capabilities: readonly DeploymentProviderCapabilityDescriptor[];
+}
+
+export interface DeploymentCredentialReference {
+  readonly provider: string;
+  readonly id: string;
+  readonly kind: string;
+}
+
+export type DeploymentSecretMaterial = string;
+
+export type DeploymentSecretResolver = (
+  reference: DeploymentCredentialReference,
+) => Promise<DeploymentSecretMaterial | null>;
+
+export interface DeploymentFailure {
+  readonly code: string;
+  readonly message: string;
+  readonly target?: AppDeployTargetId;
+  readonly provider?: string;
+}
+
+export interface DeploymentAuthenticationRequiredAction {
+  readonly type: 'authentication';
+  readonly provider: string;
+  readonly target?: AppDeployTargetId;
+  readonly code: string;
+  readonly message: string;
+}
+
+export interface DeploymentManualAction {
+  readonly type: 'manual-action';
+  readonly target: AppDeployTargetId;
+  readonly provider?: string;
+  readonly code: string;
+  readonly message: string;
+  readonly url?: string;
+}
+
+export type DeploymentRequiredAction =
+  DeploymentAuthenticationRequiredAction | DeploymentManualAction;
+
+export type DeploymentProviderResult<T> =
+  | { readonly status: 'completed'; readonly value: T }
+  | { readonly status: 'action-required'; readonly action: DeploymentRequiredAction }
+  | { readonly status: 'failed'; readonly failure: DeploymentFailure };
+
+export type DeploymentAuthenticationState =
+  | { readonly status: 'authenticated' }
+  | {
+      readonly status: 'required';
+      readonly action: DeploymentAuthenticationRequiredAction;
+    };
+
+export interface DeploymentProviderCapabilityState {
+  readonly capability: DeploymentCapability;
+  readonly status: 'available' | 'unavailable';
+  readonly reason?: string;
+}
+
+export interface DeploymentAutomatedProvisioningRequirement {
+  readonly type: 'automated';
+  readonly id: string;
+  readonly provider: string;
+  readonly target?: AppDeployTargetId;
+  readonly code: string;
+  readonly message: string;
+}
+
+export type DeploymentProvisioningRequirement =
+  | DeploymentAutomatedProvisioningRequirement
+  | { readonly type: 'authentication'; readonly action: DeploymentAuthenticationRequiredAction }
+  | { readonly type: 'manual-action'; readonly action: DeploymentManualAction };
+
+export interface DeploymentProviderSetupContext {
+  readonly target?: AppDeployTargetId;
+  readonly credentials: readonly DeploymentCredentialReference[];
+  readonly resolveSecret: DeploymentSecretResolver;
+}
+
+export interface DeploymentProviderSetupInspection {
+  readonly provider: string;
+  readonly authentication: DeploymentAuthenticationState;
+  readonly capabilities: readonly DeploymentProviderCapabilityState[];
+  readonly provisioning: readonly DeploymentProvisioningRequirement[];
+}
+
+export interface DeploymentProviderSetupAdapter {
+  readonly provider: string;
+  inspectSetup(context: DeploymentProviderSetupContext): Promise<DeploymentProviderSetupInspection>;
+}
+
+export type DeploymentStoreIdentity =
+  | { readonly target: 'android'; readonly packageName: string }
+  | { readonly target: 'ios'; readonly bundleIdentifier: string };
+
+export interface WebDeploymentPublishIntent {
+  readonly mode: 'preview' | 'production';
+  readonly alias?: string;
+  readonly environment?: string;
+}
+
+export interface WebDeploymentPublication {
+  readonly target: 'web';
+  readonly revision: string;
+  readonly provider: string;
+  readonly deploymentId: string;
+  readonly url: string;
+  readonly production: boolean;
+}
+
+export interface WebDeploymentPublishRequest {
+  readonly projectRoot: string;
+  readonly exportDirectory: string;
+  readonly revision: string;
+  readonly intent: WebDeploymentPublishIntent;
+  readonly credentials: readonly DeploymentCredentialReference[];
+  readonly resolveSecret: DeploymentSecretResolver;
+}
+
+export interface WebDeploymentPublisher {
+  publishAsync(
+    request: WebDeploymentPublishRequest,
+  ): Promise<DeploymentProviderResult<WebDeploymentPublication>>;
+}
+
+export const ANDROID_DEPLOYMENT_TRACKS = ['internal', 'alpha', 'beta', 'production'] as const;
+export type AndroidDeploymentTrack = (typeof ANDROID_DEPLOYMENT_TRACKS)[number];
+
+export const ANDROID_RELEASE_STATUSES = ['draft', 'completed'] as const;
+export type AndroidReleaseStatus = (typeof ANDROID_RELEASE_STATUSES)[number];
+
+export interface AndroidDeploymentIntent {
+  readonly buildProfile: string;
+  readonly track: AndroidDeploymentTrack;
+  readonly releaseStatus: AndroidReleaseStatus;
+}
+
+export interface AndroidBuildInspectionRequest {
+  readonly projectRoot: string;
+  readonly packageName: string;
+  readonly buildProfile: string;
+  readonly credentials: readonly DeploymentCredentialReference[];
+  readonly resolveSecret: DeploymentSecretResolver;
+}
+
+export interface AndroidBuildInspection {
+  readonly fingerprint: string;
+}
+
+export interface AndroidBuildRequest extends AndroidBuildInspectionRequest {
+  readonly expectedFingerprint: string;
+}
+
+export interface AndroidBuildArtifact {
+  readonly provider: string;
+  readonly buildId: string;
+  readonly buildProfile: string;
+  readonly fingerprint: string;
+  readonly versionCode: number;
+  readonly archiveUrl: string;
+}
+
+export interface AndroidDeploymentBuilder {
+  inspectAsync(
+    request: AndroidBuildInspectionRequest,
+  ): Promise<DeploymentProviderResult<AndroidBuildInspection>>;
+  buildAsync(request: AndroidBuildRequest): Promise<DeploymentProviderResult<AndroidBuildArtifact>>;
+}
+
+export interface AndroidPublishInspectionRequest {
+  readonly packageName: string;
+  readonly track: AndroidDeploymentTrack;
+  readonly credentials: readonly DeploymentCredentialReference[];
+  readonly resolveSecret: DeploymentSecretResolver;
+}
+
+export interface AndroidPublishInspection {
+  readonly track: AndroidDeploymentTrack;
+  readonly activeVersionCodes: readonly number[];
+}
+
+export interface AndroidPublishRequest extends AndroidPublishInspectionRequest {
+  readonly revision: string;
+  readonly releaseStatus: AndroidReleaseStatus;
+  readonly artifact: AndroidBuildArtifact;
+}
+
+export interface AndroidDeploymentPublication {
+  readonly target: 'android';
+  readonly revision: string;
+  readonly buildProvider: string;
+  readonly publishProvider: string;
+  readonly buildId: string;
+  readonly versionCode: number;
+  readonly track: AndroidDeploymentTrack;
+  readonly releaseStatus: AndroidReleaseStatus;
+}
+
+export interface AndroidDeploymentPublisher {
+  inspectAsync(
+    request: AndroidPublishInspectionRequest,
+  ): Promise<DeploymentProviderResult<AndroidPublishInspection>>;
+  publishAsync(
+    request: AndroidPublishRequest,
+  ): Promise<DeploymentProviderResult<AndroidDeploymentPublication>>;
+  verifyAsync(
+    request: AndroidPublishRequest,
+  ): Promise<DeploymentProviderResult<AndroidPublishInspection>>;
+}
+
+export interface IosDeploymentIntent {
+  readonly buildProfile: string;
+  readonly version: string;
+}
+
+export interface IosBuildInspectionRequest {
+  readonly projectRoot: string;
+  readonly bundleIdentifier: string;
+  readonly buildProfile: string;
+  readonly credentials: readonly DeploymentCredentialReference[];
+  readonly resolveSecret: DeploymentSecretResolver;
+}
+
+export interface IosBuildInspection {
+  readonly fingerprint: string;
+}
+
+export interface IosBuildRequest extends IosBuildInspectionRequest {
+  readonly expectedFingerprint: string;
+  readonly version: string;
+}
+
+export interface IosBuildArtifact {
+  readonly provider: string;
+  readonly buildId: string;
+  readonly buildProfile: string;
+  readonly fingerprint: string;
+  readonly version: string;
+  readonly buildNumber: string;
+  readonly archiveUrl: string;
+}
+
+export interface IosDeploymentBuilder {
+  inspectAsync(
+    request: IosBuildInspectionRequest,
+  ): Promise<DeploymentProviderResult<IosBuildInspection>>;
+  buildAsync(request: IosBuildRequest): Promise<DeploymentProviderResult<IosBuildArtifact>>;
+}
+
+export interface IosPublishInspectionRequest {
+  readonly bundleIdentifier: string;
+  readonly version: string;
+  readonly credentials: readonly DeploymentCredentialReference[];
+  readonly resolveSecret: DeploymentSecretResolver;
+}
+
+export interface IosPublishInspection {
+  readonly bundleIdentifier: string;
+  readonly version: string | null;
+  readonly buildNumber: string | null;
+}
+
+export interface IosPublishRequest extends IosPublishInspectionRequest {
+  readonly revision: string;
+  readonly artifact: IosBuildArtifact;
+}
+
+export interface IosDeploymentPublication {
+  readonly target: 'ios';
+  readonly revision: string;
+  readonly buildProvider: string;
+  readonly publishProvider: string;
+  readonly buildId: string;
+  readonly version: string;
+  readonly buildNumber: string;
+}
+
+export interface IosDeploymentPublisher {
+  inspectAsync(
+    request: IosPublishInspectionRequest,
+  ): Promise<DeploymentProviderResult<IosPublishInspection>>;
+  publishAsync(
+    request: IosPublishRequest,
+  ): Promise<DeploymentProviderResult<IosDeploymentPublication>>;
+  verifyAsync(request: IosPublishRequest): Promise<DeploymentProviderResult<IosPublishInspection>>;
+}
+
+export interface DeploymentProviderRegistration {
+  readonly descriptor: DeploymentProviderDescriptor;
+  readonly setup?: DeploymentProviderSetupAdapter;
+  readonly webPublisher?: WebDeploymentPublisher;
+  readonly androidBuilder?: AndroidDeploymentBuilder;
+  readonly androidPublisher?: AndroidDeploymentPublisher;
+  readonly iosBuilder?: IosDeploymentBuilder;
+  readonly iosPublisher?: IosDeploymentPublisher;
+  readonly storeListing?: DeploymentStoreListingAdapter;
+  readonly monetization?: DeploymentMonetizationAdapter;
+  readonly release?: DeploymentReleaseAdapter;
+}

package/src/types/deployRelease.ts

@@ -0,0 +1,153 @@
+import type {
+  DeploymentCredentialReference,
+  DeploymentProviderResult,
+  DeploymentSecretResolver,
+  DeploymentStoreIdentity,
+} from './deployProvider';
+
+export type ReleaseTarget = 'web' | 'android' | 'ios';
+export type ReleaseRolloutMode = 'immediate' | 'staged';
+
+export interface ReleaseNote {
+  readonly locale: string;
+  readonly text: string;
+}
+
+export interface ReleaseTargetRollout {
+  readonly mode: ReleaseRolloutMode;
+  readonly initialFraction?: string;
+}
+
+export interface ReleaseRollout {
+  readonly web?: ReleaseTargetRollout;
+  readonly android?: ReleaseTargetRollout;
+  readonly ios?: ReleaseTargetRollout;
+}
+
+export interface ReleaseDesiredState {
+  readonly version: string;
+  readonly targets: readonly ReleaseTarget[];
+  readonly notes: readonly ReleaseNote[];
+  readonly rollout: ReleaseRollout;
+  readonly revision: string;
+}
+
+export interface ReleaseObservedWebState {
+  readonly target: 'web';
+  readonly version: string | null;
+  readonly artifactRevision: string | null;
+}
+
+export interface ReleaseObservedAndroidState {
+  readonly target: 'android';
+  readonly version: string | null;
+  readonly artifactRevision: string | null;
+  readonly versionCodes: readonly string[];
+  readonly releaseNotes: readonly ReleaseNote[];
+  readonly rolloutStatus: 'missing' | 'draft' | 'inProgress' | 'halted' | 'completed';
+  readonly userFraction?: string;
+}
+
+export interface ReleaseObservedIosState {
+  readonly target: 'ios';
+  readonly version: string | null;
+  readonly artifactRevision: string | null;
+  readonly buildNumber: string | null;
+  readonly releaseNotes: readonly ReleaseNote[];
+  readonly appVersionState?: string;
+  readonly releaseType?: string;
+  readonly reviewState?: string;
+  readonly phasedReleaseState: 'INACTIVE' | 'ACTIVE' | 'PAUSED' | 'COMPLETE' | null;
+}
+
+export type ReleaseObservedTargetState =
+  ReleaseObservedWebState | ReleaseObservedAndroidState | ReleaseObservedIosState;
+
+export interface ReleaseObservedState {
+  readonly targets: readonly ReleaseObservedTargetState[];
+}
+
+export type ReleasePlanStatus = 'no-change' | 'changes' | 'waiting' | 'blocked';
+export type ReleaseStepRetry = 'safe' | 'reinspect' | 'never';
+export type ReleaseStepOperation =
+  | 'prepare'
+  | 'build'
+  | 'publish'
+  | 'sync-notes'
+  | 'submit-review'
+  | 'release'
+  | 'rollout'
+  | 'verify'
+  | 'record';
+
+export interface ReleaseDiagnostic {
+  readonly severity: 'warning' | 'error';
+  readonly code: string;
+  readonly message: string;
+  readonly target?: ReleaseTarget | 'release';
+}
+
+export interface ReleasePlanStep {
+  readonly id: string;
+  readonly target: ReleaseTarget | 'release';
+  readonly operation: ReleaseStepOperation;
+  readonly dependsOn: readonly string[];
+  readonly retry: ReleaseStepRetry;
+  readonly irreversible: boolean;
+}
+
+export interface ReleasePlan {
+  readonly status: ReleasePlanStatus;
+  readonly desiredRevision: string;
+  readonly currentRevision: string;
+  readonly steps: readonly ReleasePlanStep[];
+  readonly diagnostics: readonly ReleaseDiagnostic[];
+}
+
+export type ReleaseLifecycleControl =
+  | { readonly target: 'android'; readonly action: 'halt' | 'resume' }
+  | {
+      readonly target: 'ios';
+      readonly action: 'pause-phased' | 'resume-phased' | 'cancel-phased' | 'cancel-review';
+    };
+
+export type ReleaseMutationResult =
+  | { readonly status: 'completed' }
+  | { readonly status: 'blocked'; readonly code: string }
+  | { readonly status: 'failed'; readonly code: string };
+
+export type ReleaseControlExecutionResult =
+  | { readonly status: 'completed'; readonly mutationAttempted: boolean }
+  | { readonly status: 'blocked'; readonly mutationAttempted: false; readonly code: string }
+  | { readonly status: 'failed'; readonly mutationAttempted: boolean; readonly code: string };
+
+export interface ReleaseAdapterContext {
+  readonly identity: DeploymentStoreIdentity;
+  readonly credentials: readonly DeploymentCredentialReference[];
+  readonly resolveSecret: DeploymentSecretResolver;
+}
+
+export interface ReleaseInspectionRequest extends ReleaseAdapterContext {
+  readonly version: string;
+}
+
+export interface ReleaseStepExecutionRequest extends ReleaseAdapterContext {
+  readonly desired: ReleaseDesiredState;
+  readonly step: ReleasePlanStep;
+}
+
+export interface ReleaseControlRequest extends ReleaseAdapterContext {
+  readonly desired: ReleaseDesiredState;
+  readonly control: ReleaseLifecycleControl;
+}
+
+export type ReleaseObservedNativeState = ReleaseObservedAndroidState | ReleaseObservedIosState;
+
+export interface DeploymentReleaseAdapter {
+  readonly target: 'android' | 'ios';
+  inspectAsync(
+    request: ReleaseInspectionRequest,
+  ): Promise<DeploymentProviderResult<ReleaseObservedNativeState>>;
+  executeStepAsync(request: ReleaseStepExecutionRequest): Promise<ReleaseMutationResult>;
+  controlAsync(request: ReleaseControlRequest): Promise<ReleaseControlExecutionResult>;
+}

package/src/types/deployStoreListing.ts

@@ -0,0 +1,125 @@
+import type {
+  DeploymentCredentialReference,
+  DeploymentProviderResult,
+  DeploymentSecretResolver,
+  DeploymentStoreIdentity,
+} from './deployProvider';
+
+export type StoreListingTarget = 'android' | 'ios';
+
+export type StoreListingField =
+  | 'name'
+  | 'summary'
+  | 'description'
+  | 'keywords'
+  | 'promotionalText'
+  | 'supportUrl'
+  | 'marketingUrl'
+  | 'privacyPolicyUrl'
+  | 'promoVideoUrl';
+
+export interface StoreListingLocale {
+  readonly locale: string;
+  readonly name: string;
+  readonly summary?: string;
+  readonly description?: string;
+  readonly keywords?: readonly string[];
+  readonly promotionalText?: string;
+  readonly supportUrl?: string;
+  readonly marketingUrl?: string;
+  readonly privacyPolicyUrl?: string;
+  readonly promoVideoUrl?: string;
+}
+
+export type StoreListingAssetMediaType = 'image/jpeg' | 'image/png';
+
+export interface StoreListingAsset {
+  readonly relativePath: string;
+  readonly sha256: string;
+  readonly md5: string;
+  readonly size: number;
+  readonly mediaType: StoreListingAssetMediaType;
+}
+
+export interface StoreListingAssetSet {
+  readonly target: StoreListingTarget;
+  readonly locale: string;
+  readonly variant: string;
+  readonly assets: readonly StoreListingAsset[];
+}
+
+export interface StoreListingRemoteAssetSet {
+  readonly target: StoreListingTarget;
+  readonly locale: string;
+  readonly variant: string;
+  readonly checksum: 'md5' | 'sha256';
+  readonly hashes: readonly string[];
+}
+
+export interface StoreListingDesiredState {
+  readonly revision: string;
+  readonly locales: readonly StoreListingLocale[];
+  readonly assetSets: readonly StoreListingAssetSet[];
+}
+
+export interface StoreListingDiagnostic {
+  readonly severity: 'warning' | 'error';
+  readonly code: string;
+  readonly message: string;
+  readonly target?: StoreListingTarget;
+  readonly locale?: string;
+  readonly field?: StoreListingField;
+  readonly variant?: string;
+}
+
+export interface StoreListingTargetState {
+  readonly target: StoreListingTarget;
+  readonly locales: readonly StoreListingLocale[];
+  readonly assetSets: readonly StoreListingRemoteAssetSet[];
+  readonly supportedFields: readonly StoreListingField[];
+  readonly diagnostics: readonly StoreListingDiagnostic[];
+}
+
+export type StoreListingPlanOperation = 'create-locale' | 'update-locale' | 'replace-assets';
+
+export interface StoreListingPlanStep {
+  readonly id: string;
+  readonly target: StoreListingTarget;
+  readonly operation: StoreListingPlanOperation;
+  readonly locale: string;
+  readonly variant?: string;
+}
+
+export interface StoreListingPlan {
+  readonly status: 'no-change' | 'changes' | 'blocked';
+  readonly desiredRevision: string;
+  readonly currentRevision: string;
+  readonly steps: readonly StoreListingPlanStep[];
+  readonly diagnostics: readonly StoreListingDiagnostic[];
+}
+
+export interface StoreListingAssetReader {
+  readAsync(relativePath: string): Promise<Uint8Array>;
+}
+
+export interface StoreListingAdapterContext {
+  readonly identity: DeploymentStoreIdentity;
+  readonly credentials: readonly DeploymentCredentialReference[];
+  readonly resolveSecret: DeploymentSecretResolver;
+}
+
+export interface StoreListingSyncRequest extends StoreListingAdapterContext {
+  readonly desired: StoreListingDesiredState;
+  readonly plan: StoreListingPlan;
+  readonly assets: StoreListingAssetReader;
+}
+
+export interface DeploymentStoreListingAdapter {
+  readonly target: StoreListingTarget;
+  inspectAsync(
+    context: StoreListingAdapterContext,
+  ): Promise<DeploymentProviderResult<StoreListingTargetState>>;
+  syncAsync(
+    request: StoreListingSyncRequest,
+  ): Promise<DeploymentProviderResult<StoreListingTargetState>>;
+}

package/src/types/infraWorkload.ts

@@ -28,6 +28,8 @@ export interface InfraWorkloadPort {
   readonly name: string;
   readonly port: number;
   readonly protocol?: 'tcp' | 'udp';
+  /** Exact external listener port requested for a public single-replica workload. */
+  readonly publishedPort?: number;
 }
 
 export type InfraWorkloadHealthSpec = {