OpenAPI

优雅的跨平台脚本API，一种代码，同时支持Quantumult X, Loon, Surge, Scriptable 和Node.js。让开发者更轻松在Node.js平台调试代码。

示例

开始使用

将api-minified.js内容复制到js脚本下方。

const $ = API("weather"); // 创建一个名字为weather的脚本。默认为product环境，抑制所有log输出，保持error信息。。
const $ = API("weather", true); // 打开debug环境，打开所有log输出

Log

$.log("Something"); // 如果debug设置为false, log不会有任何输出。
$.info("Some important thing"); // 需要展示给用户的info信息，不受debug影响。
$.error("Some error message"); // 错误信息，不受debug影响。

环境判断

$.env.isQX;
$.env.isSurge;
$.env.isLoon;
$.env.isNode;
$.env.isRequest;
$.env.isResponse;
$.env.isScriptable;

通知

$.notify("title", "subtitle", "content"); // 简单标题

// URL标题
$.notify("title", "subtitle", "content", {"open-url": "https://www.bing.com"});

// 多媒体标题，QX >= build 316, 其他平台不会显示多媒体内容。
$.notify("title", "subtitle", "content", {"media-url": "https://avatars.githubusercontent.com/u/88471740"});

// 通知开关
$.isMute = ""; // 抑制通知发送(True or False, 缺省值为False)
$.isMuteLog = ""; // 抑制通知输出(True or False, 缺省值为False)

Node.js通知参数

Node.js环境中，需要使用export声明通知参数，也可以在脚本内直接赋值。参考说明文档。

// 作者信息(缺省值为笔者信息)
$.author = "";
// 微信server酱
$.SCKEY = "";
// pushplus(推送加)
$.PUSH_PLUS_TOKEN = "";
$.PUSH_PLUS_USER = "";
// iOS Bark APP
$.BARK_PUSH = "";
$.BARK_SOUND = "";
$.BARK_GROUP = "";
// Telegram 机器人
$.TG_BOT_TOKEN = "";
$.TG_USER_ID = "";
$.TG_PROXY_HOST = "";
$.TG_PROXY_PORT = "";
$.TG_PROXY_AUTH = "";
$.TG_API_HOST = "api.telegram.org";
// 钉钉机器人
$.DD_BOT_TOKEN = "";
$.DD_BOT_SECRET = "";
// 企业微信机器人
$.QYWX_KEY = "";
// 企业微信应用消息推送
$.QYWX_AM = "";
// iGot
$.IGOT_PUSH_KEY = "";
// go-cqhttp
$.GOBOT_URL = "";
$.GOBOT_TOKEN = "";
$.GOBOT_QQ = "";

HTTP

HTTP接口在Node.js使用request实现，需要用npm安装request。推荐通过如下操作安装到全局，并link。

npm install -g request
# 在工作目录
npm link request

OpenAPI提供了全部HTTP方法，包括["GET", "POST", "PUT", "DELETE", "HEAD", "OPTIONS", "PATCH"]，统一通过$.http调用：

// GET
// 简单的请求一个URL
$.http.get("https://postman-echo.com/get?foo1=bar1&foo2=bar2").then(resp => {
  // do something
});

// PUT
// 请求加入一些自定义参数
$.http.put({
    url: "https://postman-echo.com/put",
    body: "HELLO", // 设置请求body
    headers: {
      'content-type': 'text/plain'
    }, // 设置请求头
    timeout: 200 // 设置请求超时为200ms,
    // 一些钩子函数
    events: {
      onRequest: (method, options) => {
        // 请求之前可以做一些操作，比如log，注意method和options无法修改
      },
      onResponse: (resp) => {
        // 请求之后可以对resp做修改，记得返回resp！
        resp.body = JSON.parse(resp.body);
        return resp;
      },
      onTimeout: () => {
        // timeout的处理，比如可以退出APP
        $.done();
      }
    }
}).then(response => {
  // do something
});

或者你可以使用自定义参数的HTTP对象，实现一些自定义的配置。例如我们可以这样设置默认的baseURL以及默认的请求参数，比如：

headers
timeout
events

$.http = HTTP({
  baseURL: "https://www.baidu.com",
  timeout: 500,
  headers: {
    "User-Agent": "OpenAPI"
  },
  events: {
    onTimeout: () => $.error("OH NO!")
  }
});

// 设置默认的baseURL为api.github.com，并设置鉴权token
$.http = HTTP({
  baseURL: "https://api.github.com", 
  headers: {
    Authorization: `token MY_TOKEN`,
    "User-Agent":
        "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/81.0.4044.141 Safari/537.36"
  }
})

$.http.get("/gists").then(resp => {
  // do something
})

持久化

$.write("VALUE", "KEY"); // 将VALUE保存到KEY中
$.read("KEY"); // 将KEY的值取出
$.delete("KEY"); // 删除KEY的值
$.cache; // 当前脚本所有的缓存
$.done();

持久化在OpenAPI中得到了巨大改进，在不同环境下，其表现如下：

1. QX & Loon & Surge

整个API对象共用一个cache，所以$.write("VALUE", "KEY")其实只是把值保存到cache中。然后cache会被以name属性作为key保存到$prefs或者$persistentStore中。这形成了每个脚本独自的缓存空间，避免key碰撞的情况产生。

const $1 = API("APP1");
const $2 = API("APP2");

// 这是安全的！
$1.write("data", "key");
$2.write("data", "key");

2. Node.js

Node.js环境中，cache会被保存到和脚本同级目录下的name.json中。

如果希望直接存取$prefs或者$persistentStore里面的缓存，可以通过在KEY前面加#号实现。 此时Node.js环境则直接存取脚本同级目录下的root.json里面的缓存：

$.read("#KEY");
$.write(value, "#KEY");

其他

延时

$.wait(1000).then(()=>{
  // 等待1000毫秒之后执行
})

// 在任何Promise后面可以自定义delay
$.http.get("http://www.baidu.com")
.delay(1000) // 延迟1000毫秒
.then(resp => {
  // do something with response.
})

更全面的用法请查看example.js。

asvow / OpenAPI