@@ -29,6 +29,8 @@ AdGuard's Scriptlets and Redirect resources library which provides extended capa
2929 - [ ` getScriptletFunction() ` ] ( #scriptlets-api--getScriptletFunction )
3030 - [ Properties] ( #scriptlets-api-properties )
3131 - [ ` SCRIPTLETS_VERSION ` ] ( #scriptlets-api--version )
32+ - [ ` ContentScriptApi ` ] ( #scriptlets-api--content-script-api )
33+ - [ ` PolicyApi ` ] ( #scriptlets-api--content-script-api--policy-api )
3234 - [ Redirects API] ( #redirects-api )
3335 - [ Redirects class] ( #redirects-api--redirects-class )
3436 - [ ` getRedirect() ` ] ( #redirects-api--getRedirect )
@@ -463,9 +465,19 @@ interface Source {
463465 * scriptlet can be called multiple times.
464466 */
465467 uniqueId? : string ;
468+ /**
469+ * Instance of content script provided API.
470+ *
471+ * Property optional because:
472+ * - for backwards compatibility.
473+ * - currently only CoreLibs provides this API.
474+ */
475+ api? : ContentScriptApi ;
466476}
467477```
468478
479+ see also [ ` ContentScriptApi ` ] ( #scriptlets-api--content-script-api ) for more details.
480+
469481#### <a name =" scriptlets-api--getScriptletFunction " ></a > ` getScriptletFunction() `
470482
471483``` typescript
@@ -490,6 +502,139 @@ type: `string`
490502
491503Current version of scriptlets library.
492504
505+ #### <a name =" scriptlets-api--content-script-api " ></a > ` ContentScriptApi `
506+
507+ API provided by CoreLibs content script.
508+
509+ This API is used to provide a set of utilities and shared state for scriptlets
510+ running in the context of a web page. Particularly, it includes:
511+
512+ ``` typescript
513+ export interface ContentScriptApi {
514+ /**
515+ * Trusted Types Policy API utilities.
516+ */
517+ readonly policy: PolicyApi ;
518+
519+ /**
520+ * Shared state between different script and scriptlet rules.
521+ *
522+ * This object acts as a centralized repository for shared data.
523+ * - Keys represent the unique identifiers or names of the shared data.
524+ * - Values can be of any type and should correspond to the specific data shared across script rules.
525+ *
526+ * Example:.
527+ * ```adguard
528+ * ! Modify in one script rule
529+ * #%#api.shared.testKey = 'testValue'
530+ *
531+ * ! Access in another (logs 'testValue')
532+ * #%#console.log(api.shared.testKey)
533+ * ```
534+ */
535+ readonly shared: Record <string , unknown >;
536+ }
537+ ```
538+
539+ ##### <a name =" scriptlets-api--content-script-api--policy-api " ></a > ` PolicyApi `
540+
541+ Trusted Types Policy API utility.
542+
543+ This interface extends the native ` TrustedTypePolicy ` and ` TrustedTypePolicyFactory `
544+ to provide a more user-friendly API for working with Trusted Types. In case if
545+ environment doesn't support Trusted Types API, it provides polyfilled methods
546+ and properties to ensure compatibility.
547+
548+ ``` typescript
549+ export interface PolicyApi extends TrustedTypePolicy , TrustedTypePolicyFactory {
550+ /**
551+ * Is Trusted Types API supported.
552+ */
553+ isSupported: boolean ;
554+
555+ /**
556+ * TrustedType enum attached to PolicyApi.
557+ *
558+ * Reason why we attach it to instance because inside
559+ * of script and scriptlet we can't import and to not
560+ * pollute global env with custom variables.
561+ *
562+ * @example
563+ * api.policy.TrustedType.HTML // "TrustedHTML"
564+ */
565+ TrustedType: typeof TrustedType ;
566+
567+ /**
568+ * Creates Trusted Type depending on `type`:
569+ * - `TrustedHTML`
570+ * - `TrustedScript`
571+ * - `TrustedScriptURL`
572+ * - or returns back `input` if none of them applicable.
573+ *
574+ * @example
575+ * divElement.innerHTML = api.policy.create(api.policy.TrustedType.HTML, '<div></div>');
576+ *
577+ * @param type Trusted Type.
578+ * @param input Input from which creates Trusted Type.
579+ * @returns Created value.
580+ */
581+ create(type : TrustedType , input : string ): string ;
582+
583+ /**
584+ * Converts `value` of `attribute` into one of the Trusted Types:
585+ * - `TrustedHTML`
586+ * - `TrustedScript`
587+ * - `TrustedScriptURL`
588+ * - or returns back `value` if none of them applicable (`null`).
589+ *
590+ * @example
591+ * const trustedScriptURL = api.policy.convertAttributeToTrusted("script", "src", 'SOME_URL');
592+ * scriptElement.setAttribute("src", trustedScriptURL);
593+ *
594+ * @param tagName Name of an HTML tag.
595+ * @param attribute Attribute.
596+ * @param value Value of attribute that needs to be converted.
597+ * @param elementNS Element namespace, if empty defaults to the HTML namespace.
598+ * @param attrNS Attribute namespace, if empty defaults to null.
599+ * @returns Converted value.
600+ */
601+ convertAttributeToTrusted(
602+ tagName : string ,
603+ attribute : string ,
604+ value : string ,
605+ elementNS ? : string ,
606+ attrNS ? : string ,
607+ ): string ;
608+
609+ /**
610+ * Converts `value` of `property` into one of the Trusted Types:
611+ * - `TrustedHTML`
612+ * - `TrustedScript`
613+ * - `TrustedScriptURL`
614+ * - or returns back `value` if none of them applicable (`null`).
615+ *
616+ * @example
617+ * divElement.innerHTML = api.policy.convertPropertyToTrusted("div", "innerHTML", "<div></div>");
618+ *
619+ * @param tagName Name of an HTML tag.
620+ * @param property Property.
621+ * @param value Value or property.
622+ * @param elementNS Element namespace, if empty defaults to the HTML namespace.
623+ * @returns Converted value.
624+ */
625+ convertPropertyToTrusted(
626+ tagName : string ,
627+ property : string ,
628+ value : string ,
629+ elementNS ? : string ,
630+ ): string ;
631+ }
632+ ```
633+
634+ - [ TrustedTypePolicy] ( https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicy ) interface
635+ - [ TrustedTypePolicyFactory] ( https://developer.mozilla.org/en-US/docs/Web/API/TrustedTypePolicyFactory ) interface
636+
637+
493638### <a name =" redirects-api " ></a > Redirects API
494639
495640You are welcome to use redirects as a CJS modules or ESM modules:
0 commit comments