@hyprcart/app-manifest 1.0.0 → 1.0.1

package/dist/index.d.ts

@@ -1,14 +1,95 @@
-declare const supportedSurfaces: readonly ["storefront_block", "admin_surface", "checkout_ui", "checkout_function", "pixel", "event", "flow", "mcp"];
+declare const supportedSurfaces: readonly ["storefront_block", "admin_surface", "checkout_ui", "deterministic_function", "checkout_function", "pixel", "event_subscription", "background_job", "event", "flow", "mcp"];
 type AppSurfaceKind = (typeof supportedSurfaces)[number];
+declare const storefrontBlockRenderTiers: readonly ["static", "edge_render", "edge_stream"];
+type StorefrontBlockRenderTier = (typeof storefrontBlockRenderTiers)[number];
+declare const legacyStorefrontBlockRenderTiers: readonly ["edge-function", "edge-stream"];
+type LegacyStorefrontBlockRenderTier = (typeof legacyStorefrontBlockRenderTiers)[number];
+declare const hydrationTriggers: readonly ["load", "visible", "interaction", "idle", "manual"];
+type HydrationTrigger = (typeof hydrationTriggers)[number];
 type LocaleMessages = Record<string, string>;
+interface AppSurfaceSetting {
+    name: string;
+    type: "string" | "number" | "boolean" | "select" | "color" | "text" | "rich_text";
+    label?: Record<string, string> | string;
+    default?: unknown;
+    required?: boolean;
+    options?: Array<{
+        label: Record<string, string> | string;
+        value: string;
+    }>;
+    min?: number;
+    max?: number;
+}
+interface StorefrontBlockPlaceholder {
+    width: string;
+    height: string;
+    skeleton: "list" | "card" | "text" | "custom";
+    timeoutMs?: number;
+}
+interface StorefrontBlockClientIsland {
+    artifactId: string;
+    bundleUrl?: string;
+    compressedSizeBytes: number;
+    hydrationTrigger: HydrationTrigger;
+    domBoundarySelector: string;
+    consentCategory?: string;
+    exceptionId?: string;
+}
 interface AppManifestSurface {
     id: string;
     type: AppSurfaceKind;
     entry: string;
     label: Record<string, string>;
-    settings?: unknown[];
+    adminSurfaceType?: "app_home" | "settings_page" | "dashboard_widget" | "resource_panel" | "resource_action" | "bulk_action" | "command_palette_action" | "global_search_contribution" | "notification_task_contribution" | "modal_action" | "admin_ui_block";
+    settings?: AppSurfaceSetting[];
     scopes?: string[];
+    roles?: string[];
     deployable?: boolean;
+    renderTier?: StorefrontBlockRenderTier | LegacyStorefrontBlockRenderTier;
+    tier?: StorefrontBlockRenderTier | LegacyStorefrontBlockRenderTier;
+    category?: string;
+    compatiblePageTypes?: string[];
+    compatibleSlots?: string[];
+    requiredContexts?: string[];
+    cache?: {
+        maxAgeSeconds?: number;
+        staleWhileRevalidateSeconds?: number;
+        tags?: string[];
+        vary?: string[];
+    };
+    placeholder?: StorefrontBlockPlaceholder;
+    fallbackPolicy?: "omit_block" | "static_placeholder" | "previous_healthy" | "none";
+    clientIslands?: StorefrontBlockClientIsland[];
+    placement?: string | string[];
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    sandboxPolicy?: Record<string, unknown>;
+    componentKit?: {
+        minVersion: string;
+        components: string[];
+    };
+    removalBehavior?: string[];
+    dimensions?: Record<string, unknown>;
+    dataRequirements?: Record<string, unknown>;
+    consent?: {
+        category?: string;
+        events?: string[];
+        destinations?: string[];
+        retentionDays?: number;
+        regions?: string[];
+        fields?: string[];
+        bypass?: boolean;
+    };
+    determinism?: {
+        networkAccess?: boolean;
+        mutationSideEffects?: boolean;
+        operations?: string[];
+    };
+    schedule?: Record<string, unknown>;
+    retryPolicy?: Record<string, unknown>;
+    overlapPolicy?: string;
+    checkpointPolicy?: Record<string, unknown>;
+    quotaClass?: string;
 }
 interface AppManifest {
     id?: string;
@@ -20,6 +101,10 @@ interface AppManifest {
     surfaces: AppManifestSurface[];
     scopes: string[];
     translations: Record<string, LocaleMessages>;
+    launch?: LaunchReadinessDeclaration;
+    fixedSlots?: FixedSlotManifestDeclaration[];
+    storefrontTranslations?: StorefrontTranslationManifestDeclaration;
+    certification?: AppCertificationManifestDeclaration;
     egress?: string[];
     resources?: {
         bundleSizeBytes?: number;
@@ -27,8 +112,163 @@ interface AppManifest {
         memoryMb?: number;
     };
 }
+interface LaunchReadinessDeclaration {
+    adminApi?: LaunchAdminApiDeclaration;
+    appData?: LaunchAppDataDeclaration[];
+    environments?: LaunchEnvironmentDeclaration[];
+    secrets?: LaunchSecretDeclaration[];
+    settings?: LaunchMerchantSettingDeclaration[];
+    consent?: LaunchConsentMetadataDeclaration;
+    lifecycleCallbacks?: LaunchLifecycleCallbackDeclaration[];
+    assets?: LaunchAssetDeclaration[];
+    sandbox?: LaunchSandboxFixtureDeclaration;
+    evidence?: LaunchEvidenceDeclaration;
+    compatibility?: LaunchCompatibilityDeclaration;
+}
+interface LaunchAdminApiDeclaration {
+    minApiVersion: string;
+    operations: Array<{
+        operationName: string;
+        mode: "offline_app_token" | "online_app_user_token";
+        requiredScopes: string[];
+        idempotencyKeyRequired?: boolean;
+        expectedCostClass?: string;
+        examples?: string[];
+    }>;
+}
+interface LaunchAppDataDeclaration {
+    namespace: string;
+    labelKey: string;
+    purposeKey: string;
+    visibility: "private" | "merchant_visible" | "storefront_public";
+    retentionPolicyKey: string;
+    storefrontMaterialization?: {
+        enabled: boolean;
+        fields: string[];
+        cacheTags: string[];
+        varyBy: string[];
+        maxAgeSeconds?: number;
+    };
+    migrations?: Array<{
+        key: string;
+        idempotent: boolean;
+        rollbackPolicy?: Record<string, unknown>;
+    }>;
+}
+interface LaunchEnvironmentDeclaration {
+    key: "development" | "staging" | "production";
+    labelKey: string;
+    runtimeChannel: "preview" | "private" | "production";
+    promotionRequiresCertification: boolean;
+    requiredSecrets: string[];
+    optionalSecrets?: string[];
+    allowedInstallModes: Array<"sandbox" | "private_install">;
+}
+interface LaunchSecretDeclaration {
+    key: string;
+    labelKey: string;
+    purposeKey: string;
+    required: boolean;
+    scope: "app_environment" | "installation" | "storefront" | "market" | "locale";
+    runtimeExposure: "runtime_only" | "server_callback_only" | "not_exposed";
+    rotation?: {
+        overlapSeconds?: number;
+        requiredBeforePromotion?: boolean;
+    };
+}
+interface LaunchMerchantSettingDeclaration {
+    key: string;
+    label: Record<string, string>;
+    helpText?: Record<string, string>;
+    scope: Array<"organization" | "storefront" | "market" | "locale" | "role" | "resource">;
+    fields: AppSurfaceSetting[];
+}
+interface LaunchConsentMetadataDeclaration {
+    appIcon: string;
+    screenshots: string[];
+    developerName: string;
+    supportUrl: string;
+    supportEmail?: string;
+    privacyPolicyUrl: string;
+    termsUrl: string;
+    dataProcessingUrl?: string;
+    dataCategories: string[];
+    egressDestinations: string[];
+    reviewerInstructions: string;
+}
+interface LaunchLifecycleCallbackDeclaration {
+    event: "install" | "update" | "uninstall" | "disable" | "enable" | "scope_change" | "secret_rotation" | "settings_change" | "data_export" | "data_delete" | "version_promotion";
+    endpoint: string;
+    signingSecretRef: string;
+    idempotencyWindowSeconds: number;
+}
+interface LaunchAssetDeclaration {
+    key: string;
+    kind: "icon" | "screenshot" | "admin_media" | "storefront_asset" | "email_media" | "reviewer_instruction_media";
+    source: string;
+    locale?: string;
+    cacheMaxAgeSeconds?: number;
+}
+interface LaunchSandboxFixtureDeclaration {
+    fixturePackId: string;
+    seedVersion: string;
+    anonymizationRequired: boolean;
+    testModeIntegrations: string[];
+}
+interface LaunchEvidenceDeclaration {
+    repositoryUrl?: string;
+    testCommand: string;
+    buildCommand: string;
+    playwrightCoverage: string[];
+}
+interface LaunchCompatibilityDeclaration {
+    adminApiVersion: string;
+    appDataApiVersion: string;
+    runtimeVersion: string;
+    sdkVersion: string;
+    componentKitVersion: string;
+}
+interface FixedSlotManifestDeclaration {
+    pageType: "product" | "collection" | "cart" | "checkout" | "customer_profile" | "customer_account" | "order_detail" | "app_landing";
+    slotKey: string;
+    blockIds: string[];
+    settingsSchema: AppSurfaceSetting[];
+    cachePolicy: {
+        privateData: "never_shared_html" | "not_applicable";
+        tags: string[];
+        varyBy: string[];
+    };
+    previewMode: "safe_sample_buyer" | "public_only";
+}
+interface StorefrontTranslationManifestDeclaration {
+    defaultLocale: string;
+    requiredLocales: string[];
+    keys: Array<{
+        key: string;
+        description: string;
+        defaults: Record<string, string>;
+    }>;
+    fallback: {
+        mode: "locale_then_default" | "default_only";
+        missingKeyBehavior: "block_release" | "use_key";
+    };
+}
+interface AppCertificationManifestDeclaration {
+    requiredEvidence: string[];
+    playwrightCoverage: string[];
+    performanceBudgets: {
+        storefrontP95Ms: number;
+        checkoutP95Ms: number;
+        cacheHitRatio: number;
+    };
+    gapPolicy: {
+        blockOnOpenRequiredGaps: boolean;
+        requireNonLoyaltyEvidence: boolean;
+    };
+}
 declare const defaultRequiredLocales: readonly ["en", "de"];
 declare function isSupportedSurface(value: string): value is AppSurfaceKind;
+declare function normalizeStorefrontBlockRenderTier(value: string | undefined): StorefrontBlockRenderTier;
 
 type ValidationSeverity = "info" | "warning" | "error" | "blocker";
 interface ValidationIssue {
@@ -71,6 +311,25 @@ interface ValidationOptions {
 declare function validateManifest(manifest: AppManifest, options?: ValidationOptions): ValidationResult;
 declare function getTranslationStatus(manifest: AppManifest, requiredLocales: string[]): TranslationStatus;
 
+type SurfaceContractStatus = "active" | "preview" | "deferred" | "unsupported" | "rejected";
+type SurfaceContractSeverity = "info" | "warning" | "error" | "blocking";
+interface SurfaceContractDiagnostic {
+    code: string;
+    severity: SurfaceContractSeverity;
+    path: string;
+    message: string;
+    docsUrl?: string;
+}
+interface SurfaceContractResult {
+    surfaceId: string;
+    surfaceType: AppSurfaceKind;
+    status: SurfaceContractStatus;
+    runtimeOwner: "049c" | "049e" | "075a" | "deferred";
+    diagnostics: SurfaceContractDiagnostic[];
+}
+declare function validateExtensionSurfaceDeclarations(manifest: AppManifest): SurfaceContractResult[];
+declare function validateExtensionSurface(surface: AppManifestSurface, basePath?: string): SurfaceContractResult;
+
 interface GeneratedContractFile {
     path: string;
     content: string;
@@ -80,6 +339,7 @@ interface ContractGenerationResult {
     manifestHash: string;
     schemaVersion: string;
     sdkVersion: string;
+    surfaces: SurfaceContractResult[];
     files: GeneratedContractFile[];
 }
 declare function generateContracts(manifest: AppManifest, schemaVersion?: string): ContractGenerationResult;
@@ -101,7 +361,7 @@ declare function generateIdeMetadata(manifest: AppManifest): {
     schemaVersion: string;
     platformVersion: string;
     surfaceContracts: {
-        surface: "storefront_block" | "admin_surface" | "checkout_ui" | "checkout_function" | "pixel" | "event" | "flow" | "mcp";
+        surface: "storefront_block" | "admin_surface" | "checkout_ui" | "deterministic_function" | "checkout_function" | "pixel" | "event_subscription" | "background_job" | "event" | "flow" | "mcp";
         inputTypeName: string;
         outputTypeName: string;
         fixtureTypeName: string;
@@ -132,4 +392,130 @@ declare const developerToolingOperationMetadata: readonly [{
     readonly stability: "preview";
 }];
 
-export { type AppManifest, type AppManifestSurface, type AppSurfaceKind, type CompatibilityResult, type ContractGenerationResult, type GeneratedContractFile, type LocaleMessages, type ScopeImpact, type TranslationGap, type TranslationStatus, type ValidationIssue, type ValidationOptions, type ValidationResult, type ValidationSeverity, checkCompatibility, defaultRequiredLocales, developerToolingOperationMetadata, generateContracts, generateIdeMetadata, getTranslationStatus, isSupportedSurface, supportedSurfaces, validateManifest };
+declare const supportedAdminComponentKitComponents: ("Page" | "Section" | "Stack" | "InlineStack" | "Grid" | "ResourcePanel" | "AdminBlock" | "Modal" | "Sheet" | "Text" | "Heading" | "Badge" | "Status" | "DescriptionList" | "DataTable" | "Timeline" | "Metric" | "EmptyState" | "Skeleton" | "Form" | "TextField" | "NumberField" | "Select" | "Combobox" | "Checkbox" | "RadioGroup" | "DatePicker" | "FilePicker" | "ResourcePicker" | "ValidationMessage" | "Button" | "IconButton" | "Banner" | "Toast" | "InlineError" | "Progress" | "Spinner" | "Tooltip" | "ConfirmDialog" | "TitleBar" | "Breadcrumbs" | "Tabs" | "ActionList" | "ContextualSaveBar" | "CommandAction" | "SearchResult")[];
+interface AdminComponentKitManifestValidationInput {
+    minVersion?: string;
+    components?: string[];
+    tokens?: Record<string, unknown>;
+    css?: string;
+    supportedComponents?: readonly string[];
+}
+interface AdminComponentKitManifestValidationResult {
+    valid: boolean;
+    diagnostics: Array<{
+        code: string;
+        path: string;
+        message: string;
+    }>;
+}
+declare function validateAdminComponentKitManifest(input: AdminComponentKitManifestValidationInput): AdminComponentKitManifestValidationResult;
+
+declare const appGovernanceCapabilityTypes: readonly ["api_operation", "storefront_block", "admin_surface", "checkout_surface", "pixel", "event_subscription", "mcp_tool", "mcp_resource", "mcp_resource_template", "mcp_prompt", "background_job"];
+type AppGovernanceCapabilityType = (typeof appGovernanceCapabilityTypes)[number];
+declare const appGovernanceDataClasses: readonly ["public", "merchant_operational", "restricted_customer", "payment_adjacent", "auth_sensitive", "security", "operator_only"];
+type AppGovernanceDataClass = (typeof appGovernanceDataClasses)[number];
+declare const appGovernanceRiskClasses: readonly ["low", "medium", "high", "critical"];
+type AppGovernanceRiskClass = (typeof appGovernanceRiskClasses)[number];
+declare const appGovernanceCostClasses: readonly ["free", "low", "medium", "high", "operator"];
+type AppGovernanceCostClass = (typeof appGovernanceCostClasses)[number];
+declare const appGovernanceApprovalPolicies: readonly ["required", "optional", "operator_only", "automation_policy_required", "not_approvable"];
+type AppGovernanceApprovalPolicy = (typeof appGovernanceApprovalPolicies)[number];
+interface AppCapabilityDeclaration {
+    key: string;
+    type: AppGovernanceCapabilityType;
+    surface: string;
+    requiredScopes: string[];
+    optionalScopes?: string[];
+    dataClass: AppGovernanceDataClass;
+    riskClass: AppGovernanceRiskClass;
+    costClass: AppGovernanceCostClass;
+    approvalPolicy: AppGovernanceApprovalPolicy;
+    buyerVisible: boolean;
+    aiExposed?: boolean;
+    mutating?: boolean;
+}
+interface AppEgressDeclaration {
+    key: string;
+    hosts: string[];
+    class: string;
+    requiredForCapabilities: string[];
+    defaultAction: "allow" | "block" | "broker" | "log_only";
+}
+interface AppRetentionDeclaration {
+    key: string;
+    appliesTo: string[];
+    retentionMode: string;
+    uninstallAction: string;
+    merchantVisible: boolean;
+}
+interface CapabilityValidationIssue {
+    code: string;
+    path: string;
+    message: string;
+}
+interface CapabilityValidationResult {
+    valid: boolean;
+    issues: CapabilityValidationIssue[];
+}
+declare function validateAppCapabilityDeclarations(input: {
+    capabilities?: AppCapabilityDeclaration[];
+    egress?: AppEgressDeclaration[];
+    dataRetention?: AppRetentionDeclaration[];
+}): CapabilityValidationResult;
+declare function isNormalizedHostPattern(host: string): boolean;
+
+declare const aiMcpDescriptorTypes: readonly ["tool", "resource", "resource_template", "prompt"];
+type AiMcpDescriptorType = (typeof aiMcpDescriptorTypes)[number];
+declare const aiMcpHumanApprovalPolicies: readonly ["not_required", "required", "required_for_mutation", "automation_policy_allowed"];
+type AiMcpHumanApprovalPolicy = (typeof aiMcpHumanApprovalPolicies)[number];
+interface AiMcpDescriptorDeclaration {
+    name: string;
+    descriptorType: AiMcpDescriptorType;
+    capabilityKey: string;
+    requiredScopes: string[];
+    dataClass: string;
+    riskClass: string;
+    mutating: boolean;
+    humanApprovalPolicy: AiMcpHumanApprovalPolicy;
+    description?: string;
+    promptTemplate?: string;
+    resourceUriTemplate?: string;
+}
+interface AiMcpMetadataValidationIssue {
+    code: string;
+    path: string;
+    message: string;
+}
+interface AiMcpMetadataValidationResult {
+    valid: boolean;
+    issues: AiMcpMetadataValidationIssue[];
+}
+declare function validateAiMcpDescriptorMetadata(descriptors: AiMcpDescriptorDeclaration[]): AiMcpMetadataValidationResult;
+declare function classifyAiMcpMetadataAuthority(text: string): "safe_descriptor" | "untrusted_authority_claim";
+
+interface LaunchManifestValidationIssue {
+    code: string;
+    path: string;
+    message: string;
+}
+interface LaunchManifestValidationResult {
+    valid: boolean;
+    issues: LaunchManifestValidationIssue[];
+}
+declare function validateLaunchReadinessManifest(manifest: AppManifest): LaunchManifestValidationResult;
+declare function assertLaunchReadinessManifest(manifest: AppManifest): asserts manifest is AppManifest & {
+    launch: LaunchReadinessDeclaration;
+};
+
+interface NoDeployPreviewValidationResult {
+    readonly status: "valid" | "invalid";
+    readonly createdProductionState: false;
+    readonly diagnostics: readonly {
+        readonly code: string;
+        readonly message: string;
+        readonly path?: string;
+    }[];
+}
+declare function validateNoDeployPreviewManifest(manifest: AppManifest): NoDeployPreviewValidationResult;
+
+export { type AdminComponentKitManifestValidationInput, type AdminComponentKitManifestValidationResult, type AiMcpDescriptorDeclaration, type AiMcpDescriptorType, type AiMcpHumanApprovalPolicy, type AiMcpMetadataValidationIssue, type AiMcpMetadataValidationResult, type AppCapabilityDeclaration, type AppCertificationManifestDeclaration, type AppEgressDeclaration, type AppGovernanceApprovalPolicy, type AppGovernanceCapabilityType, type AppGovernanceCostClass, type AppGovernanceDataClass, type AppGovernanceRiskClass, type AppManifest, type AppManifestSurface, type AppRetentionDeclaration, type AppSurfaceKind, type AppSurfaceSetting, type CapabilityValidationIssue, type CapabilityValidationResult, type CompatibilityResult, type ContractGenerationResult, type FixedSlotManifestDeclaration, type GeneratedContractFile, type HydrationTrigger, type LaunchAdminApiDeclaration, type LaunchAppDataDeclaration, type LaunchAssetDeclaration, type LaunchCompatibilityDeclaration, type LaunchConsentMetadataDeclaration, type LaunchEnvironmentDeclaration, type LaunchEvidenceDeclaration, type LaunchLifecycleCallbackDeclaration, type LaunchManifestValidationIssue, type LaunchManifestValidationResult, type LaunchMerchantSettingDeclaration, type LaunchReadinessDeclaration, type LaunchSandboxFixtureDeclaration, type LaunchSecretDeclaration, type LegacyStorefrontBlockRenderTier, type LocaleMessages, type NoDeployPreviewValidationResult, type ScopeImpact, type StorefrontBlockClientIsland, type StorefrontBlockPlaceholder, type StorefrontBlockRenderTier, type StorefrontTranslationManifestDeclaration, type SurfaceContractDiagnostic, type SurfaceContractResult, type SurfaceContractSeverity, type SurfaceContractStatus, type TranslationGap, type TranslationStatus, type ValidationIssue, type ValidationOptions, type ValidationResult, type ValidationSeverity, aiMcpDescriptorTypes, aiMcpHumanApprovalPolicies, appGovernanceApprovalPolicies, appGovernanceCapabilityTypes, appGovernanceCostClasses, appGovernanceDataClasses, appGovernanceRiskClasses, assertLaunchReadinessManifest, checkCompatibility, classifyAiMcpMetadataAuthority, defaultRequiredLocales, developerToolingOperationMetadata, generateContracts, generateIdeMetadata, getTranslationStatus, hydrationTriggers, isNormalizedHostPattern, isSupportedSurface, legacyStorefrontBlockRenderTiers, normalizeStorefrontBlockRenderTier, storefrontBlockRenderTiers, supportedAdminComponentKitComponents, supportedSurfaces, validateAdminComponentKitManifest, validateAiMcpDescriptorMetadata, validateAppCapabilityDeclarations, validateExtensionSurface, validateExtensionSurfaceDeclarations, validateLaunchReadinessManifest, validateManifest, validateNoDeployPreviewManifest };