lucid-extension-sdk 0.0.38 → 0.0.40

package/package.json

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

package/sdk/commandtypes.d.ts

@@ -854,6 +854,7 @@ export declare type SendUIMessageQuery = {
     'd'?: JsonSerializable;
 };
 export declare type SendUIMessageResult = undefined;
+export declare type SendXHRResponseFormat = 'utf8' | 'binary';
 export declare type SendXHRQuery = {
     'url': string;
     /** HTTP method, e.g. 'GET', 'FETCH', etc. Defaults to GET */
@@ -873,11 +874,18 @@ export declare type SendXHRQuery = {
     };
     /** Timeout in milliseconds, if specified */
     'ms'?: number;
+    /**
+     * The desired format for the returned response body. Defaults to 'utf8'.
+     *
+     * - If 'utf8', the response body will be returned as a string.
+     * - If 'binary', the response body will be returned as a Uint8Array.
+     */
+    'f'?: SendXHRResponseFormat;
 };
 export declare type RawSendXHRResponse = {
     /** URL of the response after any redirects */
     'url': string;
-    /** Plain-text response body */
+    /** Plain-text or base64-encoded response body */
     't': string;
     /** Status code of the response */
     's': number;

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

@@ -1,8 +1,9 @@
+import { ExperimentalLinkUnfurlBlockProxy } from '../../document/blockclasses/linkunfurlblockproxy';
 import { UnfurlDetails } from './unfurldetails';
+import { UnfurlRefreshErrorType } from './unfurlrefresherrortype';
 export declare enum UnfurlCallbackType {
     Unfurl = "u",
-    AfterUnfurl = "a",
-    Refresh = "r"
+    AfterUnfurl = "a"
 }
 /**
  * The callbacks that handle unfurls and refreshing.
@@ -14,9 +15,25 @@ export interface UnfurlCallbacks {
      *
      * 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.
+     *
+     * This callback is also used for refresh to re-fetch the information
+     *
      * @param url The url to unfurl
      * @return The details of the unfurl or undefined
      * @ignore
      */
-    unfurlCallback: (url: string) => Promise<UnfurlDetails | undefined>;
+    unfurlCallback: (url: string) => Promise<UnfurlDetails | undefined | UnfurlRefreshErrorType>;
+    /**
+     * Callback after initial unfurl
+     * The purpose is to allow unfurlCallback to happen quickly, while afterUnfurlCallback handles longer running process
+     *
+     * For example, preview image could be added in unfurlCallback,
+     * but multiple thumbnails (or PDF conversion etc.) could be added in afterUnfurlCallback -
+     *
+     * This callback is also used for refresh to re-fetch the information
+     *
+     * @param blockProxy The block proxy of the unfurl block
+     * @ignore
+     */
+    afterUnfurlCallback?: (blockProxy: ExperimentalLinkUnfurlBlockProxy) => Promise<void>;
 }

package/sdk/core/unfurl/unfurlcallbacks.js

@@ -5,5 +5,4 @@ var UnfurlCallbackType;
 (function (UnfurlCallbackType) {
     UnfurlCallbackType["Unfurl"] = "u";
     UnfurlCallbackType["AfterUnfurl"] = "a";
-    UnfurlCallbackType["Refresh"] = "r";
 })(UnfurlCallbackType = exports.UnfurlCallbackType || (exports.UnfurlCallbackType = {}));

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

@@ -0,0 +1,5 @@
+export declare enum UnfurlRefreshErrorType {
+    AuthorizationFailure = "Authorization failure",
+    GenericFailure = "Generic failure"
+}
+export declare const unfurlRefreshErrorTypeValidator: (x: unknown) => x is UnfurlRefreshErrorType;

package/sdk/core/unfurl/unfurlrefresherrortype.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unfurlRefreshErrorTypeValidator = exports.UnfurlRefreshErrorType = void 0;
+const validators_1 = require("../validators/validators");
+var UnfurlRefreshErrorType;
+(function (UnfurlRefreshErrorType) {
+    UnfurlRefreshErrorType["AuthorizationFailure"] = "Authorization failure";
+    UnfurlRefreshErrorType["GenericFailure"] = "Generic failure";
+})(UnfurlRefreshErrorType = exports.UnfurlRefreshErrorType || (exports.UnfurlRefreshErrorType = {}));
+exports.unfurlRefreshErrorTypeValidator = (0, validators_1.stringEnumValidator)(UnfurlRefreshErrorType);

package/sdk/editorclient.d.ts

@@ -1,4 +1,4 @@
-import { CommandArgs, CommandName, UnionToIntersection } from './commandtypes';
+import { CommandArgs, CommandName, SendXHRResponseFormat, UnionToIntersection } from './commandtypes';
 import { JsonSerializable } from './core/jsonserializable';
 import { UnfurlCallbacks } from './core/unfurl/unfurlcallbacks';
 import { CollectionProxy } from './data/collectionproxy';
@@ -22,12 +22,17 @@ export interface XHRRequest {
     };
     /** If specified, this request should time out after the given number of milliseconds */
     timeoutMs?: number;
+    /**
+     * The desired format for the returned response body. Defaults to 'utf8'.
+     *
+     * - If 'utf8', the response body will be returned as a string.
+     * - If 'binary', the response body will be returned as a Uint8Array.
+     */
+    responseFormat?: SendXHRResponseFormat;
 }
-export interface XHRResponse {
+export interface BaseXHRResponse {
     /** URL of the final response, after any redirects */
     url: string;
-    /** Plain text of the response body */
-    responseText: string;
     /** HTTP status, e.g. 200 or 404 */
     status: number;
     /** Headers sent by the server in the response */
@@ -37,6 +42,17 @@ export interface XHRResponse {
     /** True if this request failed due to a timeout */
     timeout?: boolean;
 }
+export interface TextXHRResponse extends BaseXHRResponse {
+    responseFormat: 'utf8';
+    /** Plain text of the response body */
+    responseText: string;
+}
+export interface BinaryXHRResponse extends BaseXHRResponse {
+    responseFormat: 'binary';
+    /** Contents of the response body */
+    responseData: Uint8Array;
+}
+export declare type XHRResponse = TextXHRResponse | BinaryXHRResponse;
 export declare type DataActionResult = {
     /** The HTTP Status Code from the Extension Data Sync endpoint */
     'status': number;
@@ -95,7 +111,19 @@ export declare class EditorClient {
      * @returns A promise that will either resolve or reject with an XHRResponse. If the HTTP status
      *   code is not 2xx, the promise will reject.
      */
+    xhr(request: XHRRequest & {
+        responseFormat: 'utf8';
+    }): Promise<TextXHRResponse>;
+    xhr(request: XHRRequest & {
+        responseFormat: 'binary';
+    }): Promise<BinaryXHRResponse>;
     xhr(request: XHRRequest): Promise<XHRResponse>;
+    oauthXhr(providerName: string, request: XHRRequest & {
+        responseFormat: 'utf8';
+    }): Promise<TextXHRResponse>;
+    oauthXhr(providerName: string, request: XHRRequest & {
+        responseFormat: 'binary';
+    }): Promise<BinaryXHRResponse>;
     oauthXhr(providerName: string, request: XHRRequest): Promise<XHRResponse>;
     /**
      * Register a named action. These actions can be triggered from custom UI, for example as the action of a

package/sdk/editorclient.js

@@ -6,8 +6,10 @@ 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 unfurlrefresherrortype_1 = require("./core/unfurl/unfurlrefresherrortype");
 const collectionproxy_1 = require("./data/collectionproxy");
 const blockproxyregistry_1 = require("./document/blockclasses/blockproxyregistry");
+const linkunfurlblockproxy_1 = require("./document/blockclasses/linkunfurlblockproxy");
 const blockproxy_1 = require("./document/blockproxy");
 const documentproxy_1 = require("./document/documentproxy");
 const elementproxy_1 = require("./document/elementproxy");
@@ -15,6 +17,18 @@ const groupproxy_1 = require("./document/groupproxy");
 const lineproxy_1 = require("./document/lineproxy");
 const pageproxy_1 = require("./document/pageproxy");
 const registerunfurlmessage_1 = require("./message/registerunfurlmessage");
+function parseRawXHRResponse(responseFormat, raw) {
+    var _a, _b, _c, _d;
+    return Object.assign({ url: (_a = raw === null || raw === void 0 ? void 0 : raw['url']) !== null && _a !== void 0 ? _a : '', status: (_b = raw === null || raw === void 0 ? void 0 : raw['s']) !== null && _b !== void 0 ? _b : 0, headers: (_c = raw === null || raw === void 0 ? void 0 : raw['h']) !== null && _c !== void 0 ? _c : {}, timeout: raw === null || raw === void 0 ? void 0 : raw['to'] }, (responseFormat === 'utf8'
+        ? {
+            responseFormat,
+            responseText: (_d = raw === null || raw === void 0 ? void 0 : raw['t']) !== null && _d !== void 0 ? _d : 'An unknown error occurred',
+        }
+        : {
+            responseFormat,
+            responseData: (raw === null || raw === void 0 ? void 0 : raw['t']) ? (0, base64_1.decodeBase64)(raw['t']) : new Uint8Array(0),
+        }));
+}
 class EditorClient {
     constructor() {
         this.nextId = 0;
@@ -108,42 +122,26 @@ class EditorClient {
             't': timeout,
         }), this);
     }
-    /**
-     * Make a network request
-     * @param request Settings for the network request
-     * @returns A promise that will either resolve or reject with an XHRResponse. If the HTTP status
-     *   code is not 2xx, the promise will reject.
-     */
     xhr(request) {
+        const responseFormat = request.responseFormat || 'utf8';
         return this.sendCommand("xhr" /* SendXHR */, {
             'url': request.url,
             'm': request.method,
             'd': request.data,
             'h': request.headers,
             'ms': request.timeoutMs,
+            'f': responseFormat,
         })
             .then((raw) => {
-            return {
-                url: raw['url'],
-                responseText: raw['t'],
-                status: raw['s'],
-                headers: raw['h'],
-                timeout: raw['to'],
-            };
+            return parseRawXHRResponse(responseFormat, raw);
         })
             .catch((error) => {
-            var _a, _b, _c, _d;
             const raw = (0, commandtypes_1.isRawSendXHRResponse)(error) ? error : undefined;
-            throw {
-                url: (_a = raw === null || raw === void 0 ? void 0 : raw['url']) !== null && _a !== void 0 ? _a : '',
-                responseText: (_b = raw === null || raw === void 0 ? void 0 : raw['t']) !== null && _b !== void 0 ? _b : 'An unknown error occurred',
-                status: (_c = raw === null || raw === void 0 ? void 0 : raw['s']) !== null && _c !== void 0 ? _c : 0,
-                headers: (_d = raw === null || raw === void 0 ? void 0 : raw['h']) !== null && _d !== void 0 ? _d : {},
-                timeout: raw === null || raw === void 0 ? void 0 : raw['to'],
-            };
+            throw parseRawXHRResponse(responseFormat, raw);
         });
     }
     oauthXhr(providerName, request) {
+        const responseFormat = request.responseFormat || 'utf8';
         return this.sendCommand("oauth" /* SendOAuthRequest */, {
             'url': request.url,
             'm': request.method,
@@ -151,26 +149,14 @@ class EditorClient {
             'h': request.headers,
             'ms': request.timeoutMs,
             'p': providerName,
+            'f': responseFormat,
         })
             .then((raw) => {
-            return {
-                url: raw['url'],
-                responseText: raw['t'],
-                status: raw['s'],
-                headers: raw['h'],
-                timeout: raw['to'],
-            };
+            return parseRawXHRResponse(responseFormat, raw);
         })
             .catch((error) => {
-            var _a, _b, _c, _d;
             const raw = (0, commandtypes_1.isRawSendXHRResponse)(error) ? error : undefined;
-            throw {
-                url: (_a = raw === null || raw === void 0 ? void 0 : raw['url']) !== null && _a !== void 0 ? _a : '',
-                responseText: (_b = raw === null || raw === void 0 ? void 0 : raw['t']) !== null && _b !== void 0 ? _b : 'An unknown error occurred',
-                status: (_c = raw === null || raw === void 0 ? void 0 : raw['s']) !== null && _c !== void 0 ? _c : 0,
-                headers: (_d = raw === null || raw === void 0 ? void 0 : raw['h']) !== null && _d !== void 0 ? _d : {},
-                timeout: raw === null || raw === void 0 ? void 0 : raw['to'],
-            };
+            throw parseRawXHRResponse(responseFormat, raw);
         });
     }
     /**
@@ -220,20 +206,23 @@ class EditorClient {
     experimentalRegisterUnfurlHandler(domain, callbacks) {
         const action = this.getUniqueActionName();
         this.registerAction(action, async (rawMsg) => {
+            var _a;
             const msg = (0, registerunfurlmessage_1.deserializeRegisterUnfurlMessage)(rawMsg);
             switch (msg.unfurlCallbackType) {
                 case unfurlcallbacks_1.UnfurlCallbackType.Unfurl: {
                     const result = await callbacks.unfurlCallback(msg.url);
-                    if (result) {
+                    if (result && !(0, unfurlrefresherrortype_1.unfurlRefreshErrorTypeValidator)(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');
+                    if (msg.blockId) {
+                        const proxy = this.getBlockProxy(msg.blockId);
+                        if (proxy instanceof linkunfurlblockproxy_1.ExperimentalLinkUnfurlBlockProxy) {
+                            await ((_a = callbacks.afterUnfurlCallback) === null || _a === void 0 ? void 0 : _a.call(callbacks, proxy));
+                        }
+                    }
                 }
                 default:
                     break;

package/sdk/message/registerunfurlmessage.d.ts

@@ -9,18 +9,22 @@ export interface RegisterUnfurlMessage {
     url: string;
     /** @ignore */
     unfurlCallbackType: UnfurlCallbackType;
+    /** @ignore */
+    blockId?: string;
 }
 /** @ignore */
 export interface SerializedRegisterUnfurlMessage extends JsonObject {
     'id': string;
     'u': string;
     't': UnfurlCallbackType;
+    'b'?: string;
 }
 /** @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;
+    b: (x: unknown) => x is string | undefined;
 }>;
 /** @ignore */
 export declare function deserializeRegisterUnfurlMessage(raw: SerializedRegisterUnfurlMessage): RegisterUnfurlMessage;

package/sdk/message/registerunfurlmessage.js

@@ -9,6 +9,7 @@ exports.isValidRegisterUnfurlMessage = (0, validators_1.objectValidator)({
     'id': checks_1.isString,
     'u': checks_1.isString,
     't': (0, validators_1.stringEnumValidator)(unfurlcallbacks_1.UnfurlCallbackType),
+    'b': (0, validators_1.option)(checks_1.isString),
 });
 /** @ignore */
 function deserializeRegisterUnfurlMessage(raw) {
@@ -16,6 +17,7 @@ function deserializeRegisterUnfurlMessage(raw) {
         id: raw['id'],
         url: raw['u'],
         unfurlCallbackType: raw['t'],
+        blockId: raw['b'],
     };
 }
 exports.deserializeRegisterUnfurlMessage = deserializeRegisterUnfurlMessage;
@@ -25,6 +27,7 @@ function serializeRegisterUnfurlMessage(concrete) {
         'id': concrete.id,
         'u': concrete.url,
         't': concrete.unfurlCallbackType,
+        'b': concrete.blockId,
     };
 }
 exports.serializeRegisterUnfurlMessage = serializeRegisterUnfurlMessage;