CallbackURL objects can be used to open x-callback-url requests and wait for a response from the target app.

NOTE: If you want to open a URL in Safari or another app and do not need a response or x-callback-url support, use the App.openURL method on the App object.

// Open callback URL for each line in a draft
// Setup base Fantastical URL, with no parameters
declare const baseURL = "fantastical2://x-callback-url/parse/";

// split draft and loop over lines
let lines = draft.content.split("\n");
for (var line of lines) {
// create and configure callback object
var cb = CallbackURL.create();
cb.baseURL = baseURL;
cb.addParameter("sentence", line);
// open and wait for result
var success = cb.open();
if (success) {
console.log("Event created");
}
else { // something went wrong or was cancelled
console.log(cb.status);
if (cb.status == "cancelled") {
context.cancel();
}
else {
context.fail();
}
}
}

Constructors

Properties

baseURL: string

The baseURL of the request. This should include the x-callback-url base URL and action, typically something like app-scheme://x-callback-url/actionName

callbackResponse: {
    [x: string]: any;
}

An object contain and URL query parameters returned by the target app along with it’s callback response. For example, if the target app called x-success with the query parameters result=MyTestText, callbackResponse would contain {"result": "MyTestText"}.

parameters: {
    [x: string]: any;
}

Object containing string keys and values to be appended to the base url as query parameters. Values should not be pre-encoded, but will be encoded and added to the base URL automatically. Do not include x-callback parameters (x-success, x-error, x-cancel) as these will be generated by Drafts.

status:
    | "cancelled"
    | "created"
    | "success"
    | "error"
    | "timeout"
    | "invalid"

The current status of the callback. Used to check outcome after open is called. Possible values:

  • created: open has not yet been called.
  • success: x-success callback was received from target app.
  • cancelled: x-cancel callback was received from target app.
  • error: x-error callback was received from target app.
  • timeout: Waiting for the response timed out without receiving a callback URL from the target app.
  • invalid: The URL was invalid and could not be opened.
url: string

The current URL. This is provided as a debugging property, and will output the URL including the baseURL property with any configured parameters added. This property will differ from the actual URL opened when calling open() in that it will not contain the x-success, x-error and x-cancel parameters which are added dynamically at the time open() is called.

waitForResponse: boolean

If true, the script will pause and wait for the x-success, x-error or x-cancel response from the app being targeted by the URL. If false, execution of the script/action will continue immediately and no response/results will be available.

Methods

  • Add a query parameter for the outgoing URL. FIXME: can the value be anything?

    Parameters

    • key: string
    • value: any

    Returns void

  • Opens the URL with associated parameters, and waits for a callback response. Returns true if an x-success response was received from the target app, otherwise false. If false, use the "status" property to determine the type of failure.

    Returns boolean