Section type => notice key. */ private const GATED_SECTION_TYPES = array( 'customer_reviews' => 'description:customerReviews', 'compare_similar' => 'description:compareSimilar', 'related_products' => 'description:relatedProducts', ); /** * Gated types an Automation run may only write when its results go to * review first: the ones whose AI call reads text a customer wrote. * * @var string[] */ private const REVIEW_REQUIRED_TYPES = array( 'customer_reviews' ); /** * Suffix of a type's automation notice key. */ private const AUTOMATION_KEY_SUFFIX = 'Automation'; /** * Whether this site's "sections from your store" family applies to a * run. {@see \AIPT\Premium\ContentStructure\StoreSectionsService} is the * sole registrant of the filter. * * @return bool */ public function storeSectionsAllowed(): bool { return (bool) apply_filters( 'aipt_content_structure_store_sections_enabled', false ); } /** * Clamp a Description definition: disable every enabled "sections from * your store" section when this site is not entitled, or (Automation * only) every enabled review-required one when this run's job will not * route its results to review. * * Disabling here, before `SectionPlanner::plan()` runs, is what keeps * the skip free of any AI call and keeps review text out of the prompt * entirely: the isolated-call context builder is never asked for * excerpts, and no similar products are read, for a section this clamp * has already turned off. * * @param array &$definition Clamped definition (mutated in place). * @param array &$applied Accumulated appliedFreeDefaults entries. * @param array $automation_context Optional array{reviewGuaranteed?:bool}, set only for an Automation run ({@see EntitlementPolicy::apply()}). Absent outside Automation, so a non-Automation run can never trip the automation notice below. * @return void */ public function clamp( array &$definition, array &$applied, array $automation_context = array() ): void { if ( ! isset( $definition['structure']['sections'] ) || ! is_array( $definition['structure']['sections'] ) ) { return; } if ( ! $this->storeSectionsAllowed() ) { foreach ( $this->disableSections( $definition, array_keys( self::GATED_SECTION_TYPES ) ) as $type ) { $applied[] = $this->planNotice( $type ); } return; } if ( array_key_exists( 'reviewGuaranteed', $automation_context ) && false === $automation_context['reviewGuaranteed'] ) { foreach ( $this->disableSections( $definition, self::REVIEW_REQUIRED_TYPES ) as $type ) { $applied[] = $this->automationNotice( $type ); } } } /** * Disable every enabled section of $types in place. * * @param array &$definition Clamped definition (mutated in place). * @param string[] $types Section types to disable. * @return string[] Each type that had an enabled section disabled, once, in definition order (never reported when nothing changed). */ private function disableSections( array &$definition, array $types ): array { $dropped = array(); foreach ( $definition['structure']['sections'] as $i => $section ) { $type = is_array( $section ) ? (string) ( $section['type'] ?? '' ) : ''; if ( in_array( $type, $types, true ) && ! empty( $section['enabled'] ) ) { $definition['structure']['sections'][ $i ]['enabled'] = false; $dropped[ $type ] = true; } } return array_keys( $dropped ); } /** * @param string $type A gated section type. * @return array{key:string,reason:string} */ private function planNotice( string $type ): array { return $this->freeDefault( self::GATED_SECTION_TYPES[ $type ], 'contentStructureStoreSections', sprintf( /* translators: %s: the section type's name, e.g. "What customers say". */ __( '"%s" was skipped and the rest of the description was written as usual.', 'ai-product-tools' ), $this->sectionLabel( $type ) ), __( 'more description sections', 'ai-product-tools' ) ); } /** * Automation-only: this site may be fully entitled — the only reason is * that this job's own settings publish without a review step — so this * is a plain notice, never routed through PlanDenial's plan-upgrade * framing. * * @param string $type A review-required section type. * @return array{key:string,reason:string} */ private function automationNotice( string $type ): array { return array( 'key' => self::GATED_SECTION_TYPES[ $type ] . self::AUTOMATION_KEY_SUFFIX, 'reason' => sprintf( /* translators: %s: the section type's name, e.g. "What customers say". */ __( '"%s" was skipped because this job publishes without review. Send the job\'s results to review to include it.', 'ai-product-tools' ), $this->sectionLabel( $type ) ), ); } /** * @param string $type Section type. * @return string Its catalog label. */ private function sectionLabel( string $type ): string { $entry = SectionCatalog::get( $type ); return null !== $entry ? (string) $entry['label'] : $type; } /** * Every notice key this policy can report, mapped to the section type it * is about. JobExecutor reads the keys to log each notice once per tick. * * @return array Notice key => section type. */ public static function noticeTypesByKey(): array { $types = array(); foreach ( self::GATED_SECTION_TYPES as $type => $key ) { $types[ $key ] = $type; if ( in_array( $type, self::REVIEW_REQUIRED_TYPES, true ) ) { $types[ $key . self::AUTOMATION_KEY_SUFFIX ] = $type; } } return $types; } /** * This policy's own `appliedFreeDefaults` entries (identified by key), * projected into the Content Review "section notices" shape * ({@see \AIPT\Components\ContentBank\ReviewTab} client type * `ReviewSectionNotice`), so a caller staging a result into review needs * no knowledge of this policy's own key strings. Presentation only: * reuses the exact reason text {@see clamp()} already computed, never * recomputes anything. * * @param array $applied EntitlementPolicy::apply()'s appliedFreeDefaults. * @return array */ public static function sectionNoticesFrom( array $applied ): array { $types = self::noticeTypesByKey(); $notices = array(); foreach ( $applied as $entry ) { $key = is_array( $entry ) ? (string) ( $entry['key'] ?? '' ) : ''; if ( isset( $types[ $key ] ) ) { $notices[] = array( 'sectionType' => $types[ $key ], 'message' => (string) ( $entry['reason'] ?? '' ), ); } } return $notices; } }