lucid-extension-sdk 0.0.34 → 0.0.35

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "lucid-extension-sdk",
-    "version": "0.0.34",
+    "version": "0.0.35",
     "description": "Utility classes for writing Lucid Software editor extensions",
     "main": "sdk/index.js",
     "types": "sdk/index.d.ts",

package/sdk/commandtypes.d.ts

@@ -74,6 +74,7 @@ export declare const enum CommandName {
     OffsetItems = "oi",
     PatchDataItems = "pdi",
     RegisterPanel = "rp",
+    RegisterUnfurl = "ru",
     ReloadExtension = "r",
     SendOAuthRequest = "oauth",
     SendUIMessage = "suim",
@@ -327,6 +328,10 @@ export declare type CommandArgs = {
         query: RegisterPanelQuery;
         result: RegisterPanelResult;
     };
+    [CommandName.RegisterUnfurl]: {
+        query: RegisterUnfurlQuery;
+        result: RegisterUnfurlResult;
+    };
     [CommandName.ReloadExtension]: {
         query: ReloadExtensionQuery;
         result: ReloadExtensionResult;
@@ -791,6 +796,13 @@ export declare type RegisterPanelQuery = {
     'i': string;
 };
 export declare type RegisterPanelResult = undefined;
+export declare type RegisterUnfurlQuery = {
+    /** Domain to unfurl, e.g. www.google.com */
+    'd': string;
+    /** Action to call to configure the unfurl */
+    'a': string;
+};
+export declare type RegisterUnfurlResult = boolean;
 export declare type ReloadExtensionQuery = void;
 export declare type ReloadExtensionResult = undefined;
 export declare type SendOAuthRequestQuery = SendXHRQuery & {

package/sdk/commandtypes.js

@@ -59,6 +59,7 @@ exports.commandTitles = new Map([
     ["oi" /* OffsetItems */, 'OffsetItems'],
     ["pdi" /* PatchDataItems */, 'PatchDataItems'],
     ["rp" /* RegisterPanel */, 'RegisterPanel'],
+    ["ru" /* RegisterUnfurl */, 'RegisterUnfurl'],
     ["r" /* ReloadExtension */, 'ReloadExtension'],
     ["oauth" /* SendOAuthRequest */, 'SendOAuthRequest'],
     ["suim" /* SendUIMessage */, 'SendUIMessage'],

package/sdk/core/unfurl/unfurlcallbacks.d.ts

@@ -0,0 +1,22 @@
+import { UnfurlDetails } from './unfurldetails';
+export declare enum UnfurlCallbackType {
+    Unfurl = "u",
+    AfterUnfurl = "a",
+    Refresh = "r"
+}
+/**
+ * The callbacks that handle unfurls and refreshing.
+ * @ignore
+ */
+export interface UnfurlCallbacks {
+    /**
+     * Callback upon initial unfurl.
+     *
+     * This should return with minimal delay to get a partial unfurl shown to the user as quick as possible.
+     * Final configuration of the unfurl should be done in afterUnfurlCallback.
+     * @param url The url to unfurl
+     * @return The details of the unfurl or undefined
+     * @ignore
+     */
+    unfurlCallback: (url: string) => Promise<UnfurlDetails | undefined>;
+}

package/sdk/core/unfurl/unfurlcallbacks.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnfurlCallbackType = void 0;
+var UnfurlCallbackType;
+(function (UnfurlCallbackType) {
+    UnfurlCallbackType["Unfurl"] = "u";
+    UnfurlCallbackType["AfterUnfurl"] = "a";
+    UnfurlCallbackType["Refresh"] = "r";
+})(UnfurlCallbackType = exports.UnfurlCallbackType || (exports.UnfurlCallbackType = {}));

package/sdk/core/unfurl/unfurldetails.d.ts

@@ -0,0 +1,67 @@
+import { isString } from '../checks';
+import { SerializedUnfurlIframe, UnfurlIframe } from './unfurliframe';
+import { SerializedUnfurlThumbnail, UnfurlThumbnail } from './unfurlthumbnail';
+/**
+ * A definition of the details required to show an unfurl block in the editor.
+ */
+export interface UnfurlDetails {
+    /**
+     * The name of the extension attributed to the unfurl. This is a user facing name that is used to attribute the
+     * unfurl to a specific third party.
+     */
+    providerName: string;
+    /**
+     * The favicon of the provider of this unfurl.
+     */
+    providerFaviconUrl: string;
+    /**
+     * The title associated with the link being unfurled. For example, the document or web page title.
+     */
+    unfurlTitle?: string;
+    /**
+     * If the unfurl supports an expandable iframe, this configuration defines its properties.
+     */
+    iframe?: UnfurlIframe;
+    /**
+     * If the unfurl contains one or more images, this configuration defines those properties.
+     */
+    thumbnails?: UnfurlThumbnail[];
+    /**
+     * The url to show if there are no thumbnails.
+     *
+     * This can be useful to show an initial image while using other mechanisms to add all thumbnails after the unfurl is created.
+     */
+    previewImageUrl?: string;
+}
+/** @ignore */
+export interface SerializedUnfurlDetails {
+    'ProviderName': string;
+    'ProviderFaviconUrl': string;
+    'UnfurlTitle'?: string;
+    'Iframe'?: SerializedUnfurlIframe;
+    'Thumbnails'?: SerializedUnfurlThumbnail[];
+    'PreviewImageUrl'?: string;
+}
+/** @ignore */
+export declare const isValidUnfurlDetails: (subject: unknown) => subject is import("../guards").DestructureGuardedTypeObj<{
+    ProviderName: typeof isString;
+    ProviderFaviconUrl: typeof isString;
+    UnfurlTitle: (x: unknown) => x is string | undefined;
+    Iframe: (x: unknown) => x is import("../guards").DestructureGuardedTypeObj<{
+        IframeUrl: typeof isString;
+        Size: (x: unknown) => x is import("./unfurliframe").UnfurlIframeSize.Standard | undefined;
+    }> | undefined;
+    Thumbnails: (x: unknown) => x is import("../guards").DestructureGuardedTypeObj<{
+        url: typeof isString;
+        width: (x: unknown) => x is number | null | undefined;
+        /**
+         * The title associated with the link being unfurled. For example, the document or web page title.
+         */
+        height: (x: unknown) => x is number | null | undefined;
+    }>[] | undefined;
+    PreviewImageUrl: (x: unknown) => x is string | undefined;
+}>;
+/** @ignore */
+export declare function deserializeUnfurlDetails(raw: SerializedUnfurlDetails): UnfurlDetails;
+/** @ignore */
+export declare function serializeUnfurlDetails(concrete: UnfurlDetails): SerializedUnfurlDetails;

package/sdk/core/unfurl/unfurldetails.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeUnfurlDetails = exports.deserializeUnfurlDetails = exports.isValidUnfurlDetails = void 0;
+const checks_1 = require("../checks");
+const validators_1 = require("../validators/validators");
+const unfurliframe_1 = require("./unfurliframe");
+const unfurlthumbnail_1 = require("./unfurlthumbnail");
+/** @ignore */
+exports.isValidUnfurlDetails = (0, validators_1.objectValidator)({
+    'ProviderName': checks_1.isString,
+    'ProviderFaviconUrl': checks_1.isString,
+    'UnfurlTitle': (0, validators_1.option)(checks_1.isString),
+    'Iframe': (0, validators_1.option)(unfurliframe_1.isValidUnfurlIframe),
+    'Thumbnails': (0, validators_1.option)((0, validators_1.arrayValidator)(unfurlthumbnail_1.isValidUnfurlThumbnail)),
+    'PreviewImageUrl': (0, validators_1.option)(checks_1.isString),
+});
+/** @ignore */
+function deserializeUnfurlDetails(raw) {
+    var _a;
+    return {
+        providerName: raw['ProviderName'],
+        providerFaviconUrl: raw['ProviderFaviconUrl'],
+        unfurlTitle: raw['UnfurlTitle'],
+        iframe: raw['Iframe'] && (0, unfurliframe_1.deserializeUnfurlIframe)(raw['Iframe']),
+        thumbnails: (_a = raw['Thumbnails']) === null || _a === void 0 ? void 0 : _a.map((raw) => (0, unfurlthumbnail_1.deserializeUnfurlThumbnail)(raw)),
+        previewImageUrl: raw['PreviewImageUrl'],
+    };
+}
+exports.deserializeUnfurlDetails = deserializeUnfurlDetails;
+/** @ignore */
+function serializeUnfurlDetails(concrete) {
+    var _a;
+    return {
+        'ProviderName': concrete.providerName,
+        'ProviderFaviconUrl': concrete.providerFaviconUrl,
+        'UnfurlTitle': concrete.unfurlTitle,
+        'Iframe': concrete.iframe && (0, unfurliframe_1.serializeUnfurlIframe)(concrete.iframe),
+        'Thumbnails': (_a = concrete.thumbnails) === null || _a === void 0 ? void 0 : _a.map((raw) => (0, unfurlthumbnail_1.serializeUnfurlThumbnail)(raw)),
+        'PreviewImageUrl': concrete.previewImageUrl,
+    };
+}
+exports.serializeUnfurlDetails = serializeUnfurlDetails;

package/sdk/core/unfurl/unfurliframe.d.ts

@@ -0,0 +1,37 @@
+import { isString } from '../checks';
+/**
+ * An enumeration of of the supported unfurl Iframe sizes.
+ */
+export declare enum UnfurlIframeSize {
+    /**
+     * The standard iframe size.
+     */
+    Standard = "standard"
+}
+/**
+ * A definition of the properties needed to expand an iframe for an unfurl
+ */
+export interface UnfurlIframe {
+    /**
+     * The iframe url
+     */
+    iframeUrl: string;
+    /**
+     * The size of the iframe requested
+     */
+    size?: UnfurlIframeSize;
+}
+/** @ignore */
+export interface SerializedUnfurlIframe {
+    'IframeUrl': string;
+    'Size'?: UnfurlIframeSize;
+}
+/** @ignore */
+export declare const isValidUnfurlIframe: (subject: unknown) => subject is import("../guards").DestructureGuardedTypeObj<{
+    IframeUrl: typeof isString;
+    Size: (x: unknown) => x is UnfurlIframeSize.Standard | undefined;
+}>;
+/** @ignore */
+export declare function deserializeUnfurlIframe(raw: SerializedUnfurlIframe): UnfurlIframe;
+/** @ignore */
+export declare function serializeUnfurlIframe(concrete: UnfurlIframe): SerializedUnfurlIframe;

package/sdk/core/unfurl/unfurliframe.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeUnfurlIframe = exports.deserializeUnfurlIframe = exports.isValidUnfurlIframe = exports.UnfurlIframeSize = void 0;
+const checks_1 = require("../checks");
+const validators_1 = require("../validators/validators");
+/**
+ * An enumeration of of the supported unfurl Iframe sizes.
+ */
+var UnfurlIframeSize;
+(function (UnfurlIframeSize) {
+    /**
+     * The standard iframe size.
+     */
+    UnfurlIframeSize["Standard"] = "standard";
+})(UnfurlIframeSize = exports.UnfurlIframeSize || (exports.UnfurlIframeSize = {}));
+/** @ignore */
+exports.isValidUnfurlIframe = (0, validators_1.objectValidator)({
+    'IframeUrl': checks_1.isString,
+    'Size': (0, validators_1.option)((0, validators_1.stringEnumValidator)(UnfurlIframeSize)),
+});
+/** @ignore */
+function deserializeUnfurlIframe(raw) {
+    return {
+        iframeUrl: raw['IframeUrl'],
+        size: raw['Size'],
+    };
+}
+exports.deserializeUnfurlIframe = deserializeUnfurlIframe;
+/** @ignore */
+function serializeUnfurlIframe(concrete) {
+    return {
+        'IframeUrl': concrete.iframeUrl,
+        'Size': concrete.size,
+    };
+}
+exports.serializeUnfurlIframe = serializeUnfurlIframe;

package/sdk/core/unfurl/unfurlthumbnail.d.ts

@@ -0,0 +1,34 @@
+import { isString } from '../checks';
+/**
+ * A definition of a single unfurl thumbnail
+ */
+export interface UnfurlThumbnail {
+    /**
+     * The URL to fetch the image from
+     */
+    url: string;
+    /**
+     * The width of the image. This is not the height it will be displayed at, but rather the width the image actually is.
+     */
+    width?: number;
+    /**
+     * The height of the image. This is not the height it will be displayed at, but rather the height the image actually is.
+     */
+    height?: number;
+}
+/** @ignore */
+export interface SerializedUnfurlThumbnail {
+    'url': string;
+    'width'?: number | null;
+    'height'?: number | null;
+}
+/** @ignore */
+export declare const isValidUnfurlThumbnail: (subject: unknown) => subject is import("../guards").DestructureGuardedTypeObj<{
+    url: typeof isString;
+    width: (x: unknown) => x is number | null | undefined;
+    height: (x: unknown) => x is number | null | undefined;
+}>;
+/** @ignore */
+export declare function deserializeUnfurlThumbnail(raw: SerializedUnfurlThumbnail): UnfurlThumbnail;
+/** @ignore */
+export declare function serializeUnfurlThumbnail(concrete: UnfurlThumbnail): SerializedUnfurlThumbnail;

package/sdk/core/unfurl/unfurlthumbnail.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeUnfurlThumbnail = exports.deserializeUnfurlThumbnail = exports.isValidUnfurlThumbnail = void 0;
+const checks_1 = require("../checks");
+const validators_1 = require("../validators/validators");
+/** @ignore */
+exports.isValidUnfurlThumbnail = (0, validators_1.objectValidator)({
+    'url': checks_1.isString,
+    'width': (0, validators_1.nullableOption)(checks_1.isNumber),
+    'height': (0, validators_1.nullableOption)(checks_1.isNumber),
+});
+/** @ignore */
+function deserializeUnfurlThumbnail(raw) {
+    var _a, _b;
+    return {
+        url: raw['url'],
+        width: (_a = raw['width']) !== null && _a !== void 0 ? _a : undefined,
+        height: (_b = raw['height']) !== null && _b !== void 0 ? _b : undefined,
+    };
+}
+exports.deserializeUnfurlThumbnail = deserializeUnfurlThumbnail;
+/** @ignore */
+function serializeUnfurlThumbnail(concrete) {
+    return {
+        'url': concrete.url,
+        'width': concrete.width,
+        'height': concrete.height,
+    };
+}
+exports.serializeUnfurlThumbnail = serializeUnfurlThumbnail;

package/sdk/editorclient.d.ts

@@ -1,5 +1,6 @@
 import { CommandArgs, CommandName, UnionToIntersection } from './commandtypes';
 import { JsonSerializable } from './core/jsonserializable';
+import { UnfurlCallbacks } from './core/unfurl/unfurlcallbacks';
 import { BlockDefinition } from './document/blockdefinition';
 import { BlockProxy } from './document/blockproxy';
 import { ElementProxy } from './document/elementproxy';
@@ -116,6 +117,13 @@ export declare class EditorClient {
      * @param callback Function to execute when this action is invoked
      */
     registerFileUploadAction(name: string, callback: (files: FileUploadData[]) => void): void;
+    /**
+     * @ignore
+     * Registers an handler for link unfurling.
+     * @param domain The domain
+     * @param callbacks The callbacks to call when a link matching the domain is pasted.
+     */
+    experimentalRegisterUnfurlHandler(domain: string, callbacks: UnfurlCallbacks): void;
     /**
      * Remove the callback for a given action. If the action is later invoked, nothing will happen.
      * @param name name of the action to unregister

package/sdk/editorclient.js

@@ -4,6 +4,8 @@ exports.EditorClient = void 0;
 const commandtypes_1 = require("./commandtypes");
 const base64_1 = require("./core/base64");
 const checks_1 = require("./core/checks");
+const unfurlcallbacks_1 = require("./core/unfurl/unfurlcallbacks");
+const unfurldetails_1 = require("./core/unfurl/unfurldetails");
 const blockproxyregistry_1 = require("./document/blockclasses/blockproxyregistry");
 const blockproxy_1 = require("./document/blockproxy");
 const documentproxy_1 = require("./document/documentproxy");
@@ -11,6 +13,7 @@ const elementproxy_1 = require("./document/elementproxy");
 const groupproxy_1 = require("./document/groupproxy");
 const lineproxy_1 = require("./document/lineproxy");
 const pageproxy_1 = require("./document/pageproxy");
+const registerunfurlmessage_1 = require("./message/registerunfurlmessage");
 class EditorClient {
     constructor() {
         this.nextId = 0;
@@ -198,6 +201,37 @@ class EditorClient {
             }));
         });
     }
+    /**
+     * @ignore
+     * Registers an handler for link unfurling.
+     * @param domain The domain
+     * @param callbacks The callbacks to call when a link matching the domain is pasted.
+     */
+    experimentalRegisterUnfurlHandler(domain, callbacks) {
+        const action = this.getUniqueActionName();
+        this.registerAction(action, async (rawMsg) => {
+            const msg = (0, registerunfurlmessage_1.deserializeRegisterUnfurlMessage)(rawMsg);
+            switch (msg.unfurlCallbackType) {
+                case unfurlcallbacks_1.UnfurlCallbackType.Unfurl: {
+                    const result = await callbacks.unfurlCallback(msg.url);
+                    if (result) {
+                        return (0, unfurldetails_1.serializeUnfurlDetails)(result);
+                    }
+                    break;
+                }
+                case unfurlcallbacks_1.UnfurlCallbackType.AfterUnfurl: {
+                    throw new Error('UnfurlCallbackType afterUnfurl not implmeneted');
+                }
+                case unfurlcallbacks_1.UnfurlCallbackType.Refresh: {
+                    throw new Error('UnfurlCallbackType refresh not implmeneted');
+                }
+                default:
+                    break;
+            }
+            return undefined;
+        });
+        this.sendCommand("ru" /* RegisterUnfurl */, { 'd': domain, 'a': action });
+    }
     /**
      * Remove the callback for a given action. If the action is later invoked, nothing will happen.
      * @param name name of the action to unregister

package/sdk/index.d.ts

@@ -4,6 +4,7 @@ export * from './core/jsonserializable';
 export * from './core/offsettype';
 export * from './core/serializeddataerror';
 export * from './core/shapedatainheritance';
+export * from './core/unfurl/unfurldetails';
 export * from './data/collectionproxy';
 export * from './data/dataerror';
 export * from './data/dataitemproxy';

package/sdk/index.js

@@ -16,6 +16,7 @@ __exportStar(require("./core/jsonserializable"), exports);
 __exportStar(require("./core/offsettype"), exports);
 __exportStar(require("./core/serializeddataerror"), exports);
 __exportStar(require("./core/shapedatainheritance"), exports);
+__exportStar(require("./core/unfurl/unfurldetails"), exports);
 __exportStar(require("./data/collectionproxy"), exports);
 __exportStar(require("./data/dataerror"), exports);
 __exportStar(require("./data/dataitemproxy"), exports);

package/sdk/message/registerunfurlmessage.d.ts

@@ -0,0 +1,28 @@
+import { JsonObject } from '../../lucid-extension-sdk';
+import { isString } from '../core/checks';
+import { UnfurlCallbackType } from '../core/unfurl/unfurlcallbacks';
+/** @ignore */
+export interface RegisterUnfurlMessage {
+    /** @ignore */
+    id: string;
+    /** @ignore */
+    url: string;
+    /** @ignore */
+    unfurlCallbackType: UnfurlCallbackType;
+}
+/** @ignore */
+export interface SerializedRegisterUnfurlMessage extends JsonObject {
+    'id': string;
+    'u': string;
+    't': UnfurlCallbackType;
+}
+/** @ignore */
+export declare const isValidRegisterUnfurlMessage: (subject: unknown) => subject is import("../core/guards").DestructureGuardedTypeObj<{
+    id: typeof isString;
+    u: typeof isString;
+    t: (x: unknown) => x is UnfurlCallbackType;
+}>;
+/** @ignore */
+export declare function deserializeRegisterUnfurlMessage(raw: SerializedRegisterUnfurlMessage): RegisterUnfurlMessage;
+/** @ignore */
+export declare function serializeRegisterUnfurlMessage(concrete: RegisterUnfurlMessage): SerializedRegisterUnfurlMessage;

package/sdk/message/registerunfurlmessage.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.serializeRegisterUnfurlMessage = exports.deserializeRegisterUnfurlMessage = exports.isValidRegisterUnfurlMessage = void 0;
+const checks_1 = require("../core/checks");
+const unfurlcallbacks_1 = require("../core/unfurl/unfurlcallbacks");
+const validators_1 = require("../core/validators/validators");
+/** @ignore */
+exports.isValidRegisterUnfurlMessage = (0, validators_1.objectValidator)({
+    'id': checks_1.isString,
+    'u': checks_1.isString,
+    't': (0, validators_1.stringEnumValidator)(unfurlcallbacks_1.UnfurlCallbackType),
+});
+/** @ignore */
+function deserializeRegisterUnfurlMessage(raw) {
+    return {
+        id: raw['id'],
+        url: raw['u'],
+        unfurlCallbackType: raw['t'],
+    };
+}
+exports.deserializeRegisterUnfurlMessage = deserializeRegisterUnfurlMessage;
+/** @ignore */
+function serializeRegisterUnfurlMessage(concrete) {
+    return {
+        'id': concrete.id,
+        'u': concrete.url,
+        't': concrete.unfurlCallbackType,
+    };
+}
+exports.serializeRegisterUnfurlMessage = serializeRegisterUnfurlMessage;