@ankhorage/contracts 26.2.1 → 26.3.0

package/src/types/ads.ts

@@ -0,0 +1,125 @@
+/**
+ * Portable, provider-neutral advertising data contracts.
+ *
+ * Values use JSON-compatible primitives only. Provider-specific capabilities belong in optional
+ * extensions so a provider never has to imitate another provider's resource names or settings.
+ */
+
+/** ISO 4217 currency code carried with every monetary amount. */
+export type AdsCurrencyCode = Uppercase<string>;
+
+/** Integer monetary amount in micros; no currency conversion is implied by this contract. */
+export interface AdsMoney {
+  readonly currencyCode: AdsCurrencyCode;
+  readonly amountMicros: string;
+}
+
+/** Common lifecycle status shared by advertising resources. */
+export type AdsResourceStatus = 'active' | 'archived' | 'paused' | 'unknown';
+
+/** JSON-compatible value used by explicitly optional provider extensions and change values. */
+export type AdsValue =
+  boolean | number | string | null | readonly AdsValue[] | { readonly [key: string]: AdsValue };
+
+/** Provider-specific data that does not alter the common Ads contract. */
+export interface AdsProviderExtension {
+  readonly provider: string;
+  readonly values: Readonly<Record<string, AdsValue>>;
+}
+
+/** Portable identity for an advertising account or customer. */
+export interface AdsAccount {
+  readonly id: string;
+  readonly displayName?: string;
+  readonly currencyCode?: AdsCurrencyCode;
+  readonly status?: AdsResourceStatus;
+  readonly extensions?: readonly AdsProviderExtension[];
+}
+
+/** Portable campaign representation owned by an advertising account. */
+export interface AdsCampaign {
+  readonly id: string;
+  readonly accountId: string;
+  readonly name: string;
+  readonly status: AdsResourceStatus;
+  readonly extensions?: readonly AdsProviderExtension[];
+}
+
+/** Portable ad-group representation owned by a campaign. */
+export interface AdsAdGroup {
+  readonly id: string;
+  readonly accountId: string;
+  readonly campaignId: string;
+  readonly name: string;
+  readonly status: AdsResourceStatus;
+  readonly extensions?: readonly AdsProviderExtension[];
+}
+
+/** Portable advertisement representation, optionally scoped to an ad group. */
+export interface AdsAd {
+  readonly id: string;
+  readonly accountId: string;
+  readonly campaignId: string;
+  readonly adGroupId?: string;
+  readonly status: AdsResourceStatus;
+  readonly extensions?: readonly AdsProviderExtension[];
+}
+
+/** Aggregate conversion count and optional attributed monetary value. */
+export interface AdsConversionSummary {
+  readonly count: number;
+  readonly value?: AdsMoney;
+}
+
+/** Provider-neutral measured performance for an advertising resource. */
+export interface AdsPerformanceSummary {
+  readonly impressions?: number;
+  readonly clicks?: number;
+  readonly cost?: AdsMoney;
+  readonly conversions?: AdsConversionSummary;
+}
+
+/** Structured provider or validation failure without executable error behavior. */
+export interface AdsError {
+  readonly code: string;
+  readonly message: string;
+  readonly path?: readonly string[];
+  readonly extensions?: readonly AdsProviderExtension[];
+}
+
+/** Successful result carrying portable response data. */
+export interface AdsSuccessResult<T> {
+  readonly ok: true;
+  readonly value: T;
+}
+
+/** Failed result carrying structured, serializable errors. */
+export interface AdsFailureResult {
+  readonly ok: false;
+  readonly errors: readonly AdsError[];
+}
+
+/** Structured result for provider-neutral Ads operations. */
+export type AdsResult<T> = AdsFailureResult | AdsSuccessResult<T>;
+
+/** Hierarchy resource kinds addressable by a portable change. */
+export type AdsResourceKind = 'account' | 'campaign' | 'ad-group' | 'ad';
+
+/** Lifecycle stage represented by a data-only change descriptor. */
+export type AdsChangeStage = 'prepare' | 'validate' | 'apply';
+
+/** Data-only description of a planned Ads resource change. */
+export interface AdsChangeDescriptor {
+  readonly id: string;
+  readonly stage: AdsChangeStage;
+  readonly resource: {
+    readonly kind: AdsResourceKind;
+    readonly accountId: string;
+    readonly resourceId?: string;
+    readonly campaignId?: string;
+    readonly adGroupId?: string;
+  };
+  readonly operation: 'create' | 'update' | 'delete';
+  readonly values: Readonly<Record<string, AdsValue>>;
+  readonly extensions?: readonly AdsProviderExtension[];
+}

package/src/types/appManifest.ts

@@ -1,4 +1,4 @@
-import type { AppManifest } from '../types';
+import type { AppManifest } from '../types.js';
 
 export type AppManifestParseResult =
   | { readonly ok: true; readonly manifest: AppManifest }

package/src/types/infraAdapters.ts

@@ -1,5 +1,5 @@
-import type { AppEnvironmentId } from '../environments';
-import type { INFRA_ADAPTER_CATALOG } from '../infraCatalog';
+import type { AppEnvironmentId } from '../environments.js';
+import type { INFRA_ADAPTER_CATALOG } from '../infraCatalog.js';
 import type {
   InfraDestroyRequest,
   InfraGeneratedArtifact,
@@ -9,7 +9,7 @@ import type {
   InfraPlanAction,
   InfraResourceStatus,
   InfraResult,
-} from './infraLifecycle';
+} from './infraLifecycle.js';
 import type {
   InfraAdapterId,
   InfraComputeProviderId,
@@ -17,10 +17,10 @@ import type {
   InfraEnvironmentSpec,
   InfraRuntimeProviderId,
   InfraRuntimeSelection,
-} from './infraManifest';
-import type { InfraControlPlaneCredentialRef, InfraSecretReference } from './infraSecrets';
-import type { InfraComputeTarget } from './infraTargets';
-import type { InfraWorkloadSpec } from './infraWorkload';
+} from './infraManifest.js';
+import type { InfraControlPlaneCredentialRef, InfraSecretReference } from './infraSecrets.js';
+import type { InfraComputeTarget } from './infraTargets.js';
+import type { InfraWorkloadSpec } from './infraWorkload.js';
 
 /** Package exports must match this exact catalog entry; optional operations are advertised explicitly. */
 export type InfraAdapterDescriptor<P extends InfraAdapterId = InfraAdapterId> = {

package/src/types/infraLifecycle.ts

@@ -1,7 +1,7 @@
-import type { AppEnvironmentId } from '../environments';
-import type { InfraAdapterId } from './infraManifest';
-import type { InfraSecretReference } from './infraSecrets';
-import type { InfraComputeTarget } from './infraTargets';
+import type { AppEnvironmentId } from '../environments.js';
+import type { InfraAdapterId } from './infraManifest.js';
+import type { InfraSecretReference } from './infraSecrets.js';
+import type { InfraComputeTarget } from './infraTargets.js';
 
 /** Identity must be verified before mutation; unowned resources must never be pruned. */
 export interface InfraResourceIdentity {

package/src/types/infraManifest.ts

@@ -1,11 +1,11 @@
-import type { AuthFlowConfig, AuthOAuthConfig } from '../auth';
-import type { EntityRegistry, SerializableSet, ValueMap } from '../collections';
-import type { ApiDefinitionRegistry, DataContractValue } from '../data';
-import type { AppEnvironmentId } from '../environments';
-import type { INFRA_ADAPTER_CATALOG, INFRA_RUNTIME_COMPATIBILITY } from '../infraCatalog';
-import type { AuthProfileSpec, AuthScope, AuthSignInSpec, AuthSignUpSpec } from '../types';
-import type { InfraControlPlaneCredentialRef } from './infraSecrets';
-import type { InfraWorkloadRegistry } from './infraWorkload';
+import type { AuthFlowConfig, AuthOAuthConfig } from '../auth.js';
+import type { EntityRegistry, SerializableSet, ValueMap } from '../collections.js';
+import type { ApiDefinitionRegistry, DataContractValue } from '../data/index.js';
+import type { AppEnvironmentId } from '../environments.js';
+import type { INFRA_ADAPTER_CATALOG, INFRA_RUNTIME_COMPATIBILITY } from '../infraCatalog.js';
+import type { AuthProfileSpec, AuthScope, AuthSignInSpec, AuthSignUpSpec } from '../types.js';
+import type { InfraControlPlaneCredentialRef } from './infraSecrets.js';
+import type { InfraWorkloadRegistry } from './infraWorkload.js';
 
 export type InfraAdapterId = keyof typeof INFRA_ADAPTER_CATALOG;
 export type InfraCapability =

package/src/types/infraSecrets.ts

@@ -1,4 +1,4 @@
-import type { AppEnvironmentId } from '../environments';
+import type { AppEnvironmentId } from '../environments.js';
 
 /** Bootstrap credentials cannot depend on the managed secret store being provisioned. */
 export interface InfraControlPlaneCredentialRef {

package/src/types/infraTargets.ts

@@ -1,4 +1,4 @@
-import type { InfraControlPlaneCredentialRef } from './infraSecrets';
+import type { InfraControlPlaneCredentialRef } from './infraSecrets.js';
 
 /** Portable runtime target state contains credential identity only, never resolved values. */
 export type InfraComputeTarget = {

package/src/types/infraWorkload.ts

@@ -1,5 +1,5 @@
-import type { EntityRegistry, SerializableSet, ValueMap } from '../collections';
-import type { InfraControlPlaneCredentialRef, InfraSecretReference } from './infraSecrets';
+import type { EntityRegistry, SerializableSet, ValueMap } from '../collections.js';
+import type { InfraControlPlaneCredentialRef, InfraSecretReference } from './infraSecrets.js';
 
 export interface InfraWorkloadArtifact {
   readonly kind: 'image';

package/src/types.ts

@@ -1,22 +1,22 @@
 import type { ColorHarmony } from '@ankhorage/color-theory';
 
-import type { AuthIdentifierKind, AuthSignUpField } from './auth';
+import type { AuthIdentifierKind, AuthSignUpField } from './auth.js';
 import type {
   BindingExpression,
   ComponentDataBindingRegistry,
   ScreenDataLoaderDefinition,
-} from './bindings';
-import type { EntityRegistry } from './collections';
-import type { DataSourceRegistry } from './data';
-import type { AppDeployManifest } from './deploy';
-import type { InfraManifest } from './infra';
-import type { MediaAssetReference, MediaManifest } from './media';
-import type { AppNavigatorManifest } from './navigator';
-import type { RepositoryManifest } from './repository';
-import type { ScreenRequirements } from './requirements';
-import type { SerializableValue } from './serializable';
-import type { AppStateSpec } from './state';
-import type { ThemeGlobalTokenOverrides, ThemeRecipeOverrides } from './theme';
+} from './bindings.js';
+import type { EntityRegistry } from './collections.js';
+import type { DataSourceRegistry } from './data/index.js';
+import type { AppDeployManifest } from './deploy.js';
+import type { InfraManifest } from './infra.js';
+import type { MediaAssetReference, MediaManifest } from './media.js';
+import type { AppNavigatorManifest } from './navigator.js';
+import type { RepositoryManifest } from './repository.js';
+import type { ScreenRequirements } from './requirements.js';
+import type { SerializableValue } from './serializable.js';
+import type { AppStateSpec } from './state.js';
+import type { ThemeGlobalTokenOverrides, ThemeRecipeOverrides } from './theme.js';
 
 export interface ThemeModeConfig {
   primaryColor: string;

package/src/ui.ts

@@ -1,5 +1,5 @@
-import type { MediaAssetKind } from './media';
-import type { ComponentEventDtoKind } from './types';
+import type { MediaAssetKind } from './media.js';
+import type { ComponentEventDtoKind } from './types.js';
 
 export type UiComponentCategory = 'component' | 'foundation' | 'layout' | 'pattern';