@adobe/ccweb-add-on-sdk-types 1.0.0 → 1.1.1

package/{script → sandbox}/global.d.ts

@@ -23,8 +23,8 @@
  ********************************************************************************/
 
 /**
- * Here are various global objects and Web APIs available for use in script code.
- * Please note, script runtime exposes only a subset of functionalities
+ * Here are various global objects and Web APIs available for use in document sandbox code.
+ * Please note, document sandbox runtime exposes only a subset of functionalities
  * exposed by standard Web APIs.
  */
 declare global {
@@ -40,11 +40,6 @@ declare global {
         assert(assertion?: boolean, msg?: string, ...subst: any[]): void;
     }
 
-    function setTimeout(functionRef: Function, delay: number, ...params: any[]): number;
-    function clearTimeout(timeoutID: number): void;
-    function setInterval(functionRef: Function, delay: number, ...params: any[]): number;
-    function clearInterval(intervalID: number): void;
-
     interface Blob {
         readonly size: number;
         readonly type: string;
@@ -53,6 +48,10 @@ declare global {
         text(): Promise<string>;
     }
 
+    interface BlobPropertyBag {
+        type?: string;
+    }
+
     var Blob: {
         prototype: Blob;
         new (blobParts?: BlobPart[], options?: BlobPropertyBag): Blob;

package/{script → sandbox}/index.d.ts

@@ -22,7 +22,7 @@
  * SOFTWARE.
  ********************************************************************************/
 
-export * from "./express.js";
+export * from "./express-document-sdk.js";
 export * from "./global.js";
-export * from "./script-sdk.js";
-export { default } from "./script-sdk.js";
+export * from "./add-on-sdk-document-sandbox.js";
+export { default } from "./add-on-sdk-document-sandbox.js";

package/ui/ui-sdk.d.ts

@@ -22,8 +22,6 @@
  * SOFTWARE.
  ********************************************************************************/
 
-import { Remote } from "comlink";
-
 /**
  * Base interface for all type of add-ons
  */
@@ -134,7 +132,16 @@ export declare enum AppEvent {
     /**
      * triggered when drag is complete on the currently dragged element.
      */
-    dragend = "dragend"
+    dragend = "dragend",
+
+    /**
+     * triggered when the document id is available in the application.
+     */
+    documentIdAvailable = "documentIdAvailable",
+    /**
+     * triggered when the document title is changed in the application.
+     */
+    documentTitleChange = "documentTitleChange"
 }
 
 export declare type AppEventHandlerType<Event extends AppEventType> = (data: AppEventsTypeMap[Event]) => void;
@@ -147,6 +154,9 @@ declare interface AppEventsTypeMap {
     [AppEvent.localechange]: AppLocaleChangeEventData;
     [AppEvent.dragstart]: AppDragStartEventData;
     [AppEvent.dragend]: AppDragEndEventData;
+
+    [AppEvent.documentIdAvailable]: DocumentIdAvailableEventData;
+    [AppEvent.documentTitleChange]: DocumentTitleChangeEventData;
 }
 
 export declare type AppEventType = keyof AppEventsTypeMap & string;
@@ -552,9 +562,35 @@ declare interface Document_2 {
      * Create renditions
      */
     createRenditions(renditionOptions: RenditionOptions, renditionIntent?: RenditionIntent): Promise<Rendition[]>;
+    /**
+     * Get metadata of all or range of pages of the document
+     */
+    getPagesMetadata(options: PageMetadataOptions): Promise<PageMetadata[]>;
+    /**
+     * Get document id
+     */
+    id(): Promise<string | undefined>;
+    /**
+     * Get document name/title
+     */
+    title(): Promise<string>;
 }
 export { Document_2 as Document };
 
+/**
+ * The payload data sent to the document id available event handler.
+ */
+declare interface DocumentIdAvailableEventData {
+    documentId: string | undefined;
+}
+
+/**
+ * The payload data sent to the document title change event handler.
+ */
+declare interface DocumentTitleChangeEventData {
+    documentTitle: string;
+}
+
 /**
  * Interface to hold various callbacks which are required to be passed to enableDragToDocument.
  */
@@ -673,11 +709,64 @@ export declare interface JpgRenditionOptions extends RenditionOptions {
     };
 }
 
+/**
+ * Takes the raw type of a remote object or function as a remote thread would see it through a proxy (e.g. when
+ * passed in as a function argument) and returns the type the local thread has to supply.
+ * Creation of new class objects is not allowed.
+ *
+ * This is the inverse of `Remote<T>`. It takes a `Remote<T>` and returns its original input `T`.
+ */
+declare type Local<T> = LocalObject<T> &
+    (T extends (...args: infer TArguments) => infer TReturn
+        ? (
+              ...args: {
+                  [I in keyof TArguments]: ProxyOrClone<TArguments[I]>;
+              }
+          ) => MaybePromise<UnproxyOrClone<Unpromisify<TReturn>>>
+        : unknown) &
+    (T extends {
+        new (...args: infer TArguments): infer TInstance;
+    }
+        ? {
+              new: never;
+          }
+        : unknown);
+
 /**
  * Placeholder for future localization support
  */
 export declare type LocalizedString = string;
 
+/**
+ * Takes the type of an object as a remote thread would see it through a proxy (e.g. when passed in as a function
+ * argument) and returns the type that the local thread has to supply.
+ *
+ * This does not handle call signatures, which is handled by the more general `Local<T>` type.
+ *
+ * This is the inverse of `RemoteObject<T>`.
+ *
+ * @template T The type of a proxied object.
+ */
+declare type LocalObject<T> = {
+    [P in keyof T]: LocalProperty<T[P]>;
+};
+
+/**
+ * Takes the raw type of a property as a remote thread would see it through a proxy (e.g. when passed in as a function
+ * argument) and returns the type that the local thread has to supply.
+ *
+ * This is the inverse of `RemoteProperty<T>`.
+ *
+ * Note: This needs to be its own type alias, otherwise it will not distribute over unions. See
+ * https://www.typescriptlang.org/docs/handbook/advanced-types.html#distributive-conditional-types
+ */
+declare type LocalProperty<T> = T extends Function | ProxyMarked ? Local<T> : Unpromisify<T>;
+
+/**
+ * Expresses that a type can be either a sync or async.
+ */
+declare type MaybePromise<T> = Promise<T> | T;
+
 /**
  * Media Attributes for importing media
  */
@@ -707,6 +796,53 @@ export declare interface OAuth {
     authorizeWithOwnRedirect(request: AuthorizeWithOwnRedirectRequest): Promise<AuthorizationResult>;
 }
 
+/**
+ * Represents the metadata of the Page
+ */
+export declare interface PageMetadata {
+    /**
+     * Unique id that represent the given page
+     */
+    id: string;
+    /**
+     * Page title
+     */
+    title: string;
+    /**
+     * Page size in pixels
+     */
+    size: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Whether page contains any premium content
+     */
+    hasPremiumContent: boolean;
+    /**
+     * Whether page contains timelines
+     */
+    hasTemporalContent: boolean;
+    /**
+     * Pixels per inch of the page
+     */
+    pixelsPerInch?: number;
+}
+
+/**
+ * Options for fetching page metadata
+ */
+export declare interface PageMetadataOptions {
+    /**
+     * Page range of the document to get the metadata
+     */
+    range: Range_2;
+    /**
+     * Ids of the pages (Only required if the range is "specificPages")
+     */
+    pageIds?: string[];
+}
+
 export declare interface PageRendition extends Rendition {
     /**
      * Page rendition type
@@ -716,6 +852,10 @@ export declare interface PageRendition extends Rendition {
      * Page title
      */
     title: string;
+    /**
+     * Page metadata
+     */
+    metadata: PageMetadata;
 }
 
 export declare interface PngRenditionOptions extends RenditionOptions {
@@ -738,6 +878,29 @@ export declare interface PngRenditionOptions extends RenditionOptions {
     };
 }
 
+/**
+ * Takes a type and wraps it in a Promise, if it not already is one.
+ * This is to avoid `Promise<Promise<T>>`.
+ *
+ * This is the inverse of `Unpromisify<T>`.
+ */
+declare type Promisify<T> = T extends Promise<unknown> ? T : Promise<T>;
+
+/**
+ * Interface of values that were marked to be proxied with `Runtime.apiProxy()`.
+ * Can also be implemented by classes.
+ */
+declare interface ProxyMarked {
+    [proxyMarker]: true;
+}
+
+declare const proxyMarker: unique symbol;
+
+/**
+ * Proxies `T` if it is a `ProxyMarked`, clones it otherwise (as handled by structured cloning and transfer handlers).
+ */
+declare type ProxyOrClone<T> = T extends ProxyMarked ? Remote<T> : T;
+
 /**
  * Rendition page range
  */
@@ -749,10 +912,55 @@ declare enum Range_2 {
     /**
      * Generate rendition for all the pages
      */
-    entireDocument = "entireDocument"
+    entireDocument = "entireDocument",
+    /**
+     * Generate rendition for specific pages
+     */
+    specificPages = "specificPages"
 }
 export { Range_2 as Range };
 
+/**
+ * Takes the raw type of a remote object or function in the other thread and returns the type as it is visible to
+ * the local thread from the proxy return value of `Runtime.apiProxy()`.
+ * Creation of new class objects is not allowed.
+ */
+declare type Remote<T> = RemoteObject<T> &
+    (T extends (...args: infer TArguments) => infer TReturn
+        ? (
+              ...args: {
+                  [I in keyof TArguments]: UnproxyOrClone<TArguments[I]>;
+              }
+          ) => Promisify<ProxyOrClone<Unpromisify<TReturn>>>
+        : unknown) &
+    (T extends {
+        new (...args: infer TArguments): infer TInstance;
+    }
+        ? {
+              new: never;
+          }
+        : unknown);
+
+/**
+ * Takes the raw type of a remote object in the other thread and returns the type as it is visible to the local thread
+ * when proxied with `Runtime.apiProxy()`.
+ *
+ * This does not handle call signatures, which is handled by the more general `Remote<T>` type.
+ *
+ * @template T The raw type of a remote object as seen in the other thread.
+ */
+declare type RemoteObject<T> = {
+    [P in keyof T]: RemoteProperty<T[P]>;
+};
+
+/**
+ * Takes the raw type of a remote property and returns the type that is visible to the local thread on the proxy.
+ *
+ * Note: This needs to be its own type alias, otherwise it will not distribute over unions.
+ * See https://www.typescriptlang.org/docs/handbook/advanced-types.html#distributive-conditional-types
+ */
+declare type RemoteProperty<T> = T extends Function | ProxyMarked ? Remote<T> : Promisify<T>;
+
 export declare interface Rendition {
     /**
      * Type of Rendition
@@ -809,6 +1017,10 @@ export declare interface RenditionOptions {
      * Format of the rendition
      */
     format: RenditionFormat;
+    /**
+     * Ids of the pages (Only required if the range is "specificPages")
+     */
+    pageIds?: string[];
 }
 
 /**
@@ -831,21 +1043,20 @@ export declare interface Runtime {
     dialog?: Dialog;
 
     /**
-     * @experimental - Experimental API
      * Exposes the concrete object/function of type T,
-     * which can be accessed into different runtime part of this AddOn e.g., "script" runtime.
+     * which can be accessed into different runtime part of this AddOn e.g., "document model sandbox" runtime.
      * Note that only concrete objects / class instances are supported. We can't expose entire class
      * from one runtime and create instance of that class in another runtime. Trying to do
      * so may result in undefined behaviour.
      * @param apiObj - the concrete object to expose to other runtimes
      *
      * Notes:
-     * 1. This method is only present if this is a panel runtime and it has an associated script runtime.
+     * 1. This method is only present if this UI runtime represents panel UI (not RuntimeType.dialog),
+     *    and the add-on has an associated document model sandbox. The sandbox runtime provides similar method to expose APIs in the other direction.
      * 2. This method call is allowed only once. Subsequent calls are ignored.
      */
     exposeApi?<T>(apiObj: T): void;
     /**
-     * @experimental - Experimental API
      * Requests a promise based proxy object for other runtimes, which will be used
      * by this UI runtime to directly call the APIs exposed (using exposeApi) from the other runtimes.
      * await or .then is necessary, since returned object is a promise.
@@ -855,7 +1066,8 @@ export declare interface Runtime {
      * @see https://github.com/GoogleChromeLabs/comlink/blob/main/src/comlink.ts#L117
      *
      * Note:
-     * 1. This method is only present if this is a panel runtime and it has an associated script runtime.
+     * 1. This method is only present if this UI runtime represents panel UI (not RuntimeType.dialog),
+     *    and the add-on has an associated document model sandbox. The sandbox runtime provides similar method to get proxy object in the other direction.
      * 2. Calling the method again for same runtime type will return a new proxy object without any behavior difference.
      */
     apiProxy?<T>(runtimeType: RuntimeType): Promise<Remote<T>>;
@@ -871,9 +1083,14 @@ export declare enum RuntimeType {
      */
     dialog = "dialog",
     /**
-     * Add-On's script runtime - js runtime that hosts the add-ons script / document authoring logic.
+     * @deprecated Use `documentSandbox` instead.
+     * Add-On's document model sandbox - JS runtime that hosts add-on code that has direct access to the full model.
+     */
+    script = "script",
+    /**
+     * Add-On's document model sandbox - JS runtime that hosts add-on code that has direct access to the full model.
      */
-    script = "script"
+    documentSandbox = "documentSandbox"
 }
 
 export declare type SimpleDialogOptions = AlertDialogOptions | InputDialogOptions;
@@ -898,6 +1115,19 @@ export declare interface UI {
 
 declare type UiTheme = "light" | "dark" | "lightest" | "darkest";
 
+/**
+ * Takes a type that may be Promise and unwraps the Promise type.
+ * If `P` is not a Promise, it returns `P`.
+ *
+ * This is the inverse of `Promisify<T>`.
+ */
+declare type Unpromisify<P> = P extends Promise<infer T> ? T : P;
+
+/**
+ * Inverse of `ProxyOrClone<T>`.
+ */
+declare type UnproxyOrClone<T> = T extends RemoteObject<ProxyMarked> ? Local<T> : T;
+
 /**
  * Types of dialog variants supported.
  */

package/script/script-sdk.d.ts

@@ -1,101 +0,0 @@
-/********************************************************************************
- * MIT License
-
- * © Copyright 2023 Adobe. All rights reserved.
-
- * Permission is hereby granted, free of charge, to any person obtaining a copy
- * of this software and associated documentation files (the "Software"), to deal
- * in the Software without restriction, including without limitation the rights
- * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
- * copies of the Software, and to permit persons to whom the Software is
- * furnished to do so, subject to the following conditions:
- * 
- * The above copyright notice and this permission notice shall be included in all
- * copies or substantial portions of the Software.
- * 
- * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
- * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
- * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
- * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
- * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
- * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
- * SOFTWARE.
- ********************************************************************************/
-
-import { Remote } from "comlink";
-
-/**
- * Represents the instance of this AddOn.
- * The instance contains the necessary details like the associated Runtime etc.
- */
-export declare class AddOn {
-    /**
-     * Get the runtime instance, which represents
-     * the execution environment for this AddOn.
-     */
-    get runtime(): Runtime;
-}
-
-/**
- * The APIs provided by AddOn Script SDK.
- * The APIs are exposed as an ES6 module.
- */
-export declare class AddOnScriptSDK {
-    /**
-     * Returns the instance of this AddOn.
-     * @see AddOn
-     */
-    get instance(): AddOn;
-}
-
-declare const addOnScriptSdk: AddOnScriptSDK;
-export default addOnScriptSdk;
-
-/**
- * The instance of Runtime this AddOn is running into.
- * It contains methods to expose APIs from this runtime
- * and getting access to APIs exposed by other runtimes.
- */
-export declare class Runtime {
-    /**
-     * The runtime-type of this Runtime.
-     * Will always be "script".
-     */
-    get type(): RuntimeType.script;
-    /**
-     * Exposes the concrete object/function of type T,
-     * which can be accessed into different runtime part of this AddOn e.g., "panel" (iframe) runtime.
-     * Note that only concrete objects / class instances are supported. We can't expose entire class
-     * from one runtime and create instance of that class in another runtime. Trying to do
-     * so may result in undefined behaviour.
-     * @param obj - the concrete object to expose to other runtimes
-     * Note: This method call is allowed only once. Subsequent calls are ignored.
-     */
-    exposeApi<T>(obj: T): void;
-    /**
-     * Requests a promise based proxy object for other runtimes, which will be used
-     * by this script runtime to directly call the APIs exposed (using exposeApi) from the other runtimes (e.g., UI runtime).
-     * await or .then is necessary, since returned object is a promise.
-     * @param runtimeType - the runtime, for which proxy object needs to be created.
-     * @returns a promise which may resolve to a proxy or reject with rejection reason.
-     * The promise resolves to API proxy object exposed by desired runtime, as soon as the other runtime is finished initializing.
-     * Note: Calling the method again for same runtime type will return a new proxy object without any behavior difference.
-     */
-    apiProxy(runtimeType: RuntimeType): Promise<Remote<unknown>>;
-}
-
-/**
- * Supported runtime types for this AddOn.
- */
-export declare enum RuntimeType {
-    /**
-     * Represents iframe runtime part of this AddOn.
-     */
-    panel = "panel",
-    /**
-     * Represents Script runtime part of this AddOn.
-     */
-    script = "script"
-}
-
-export {};