runline 0.33.0 → 0.34.0

package/dist/plugins/graphql/src/index.js

@@ -1,11 +1,28 @@
+import { credentialJson, graphqlFailed } from "../../_shared/credentials.js";
+import { endpoint, graphqlCredential, publicHeaders } from "./credentials.js";
+/** One GraphQL request to the configured endpoint; `errors` in the answer is a failure. */
+async function gql(ctx, body) {
+    const config = ctx.connection.config;
+    const answer = await credentialJson(ctx, graphqlCredential, "graphql", {
+        target: "api",
+        path: endpoint(config).path,
+        method: "POST",
+        json: body,
+        headers: publicHeaders(config),
+    });
+    if (answer.errors)
+        throw graphqlFailed("graphql", answer.errors);
+    return answer.data;
+}
 export default function graphql(rl) {
     rl.setName("graphql");
     rl.setVersion("0.1.0");
+    rl.setCredential(graphqlCredential);
     rl.setConnectionSchema({
         endpoint: {
             type: "string",
             required: true,
-            description: "GraphQL endpoint URL",
+            description: "GraphQL endpoint URL (HTTPS)",
             env: "GRAPHQL_ENDPOINT",
         },
         headerAuth: {
@@ -17,7 +34,7 @@ export default function graphql(rl) {
         headers: {
             type: "object",
             required: false,
-            description: "Additional headers as key-value pairs",
+            description: "Additional public headers as key-value pairs; a secret belongs in headerAuth",
         },
     });
     rl.registerAction("query", {
@@ -42,52 +59,18 @@ export default function graphql(rl) {
         },
         async execute(input, ctx) {
             const { query, variables, operationName } = input;
-            const cfg = ctx.connection.config;
-            const endpoint = cfg.endpoint;
-            const hdrs = {
-                "Content-Type": "application/json",
-            };
-            if (cfg.headerAuth)
-                hdrs.Authorization = cfg.headerAuth;
-            if (cfg.headers) {
-                for (const [k, v] of Object.entries(cfg.headers)) {
-                    hdrs[k] = v;
-                }
-            }
             const body = { query };
             if (variables)
                 body.variables = variables;
             if (operationName)
                 body.operationName = operationName;
-            const res = await fetch(endpoint, {
-                method: "POST",
-                headers: hdrs,
-                body: JSON.stringify(body),
-            });
-            if (!res.ok)
-                throw new Error(`GraphQL error ${res.status}: ${await res.text()}`);
-            const data = (await res.json());
-            if (data.errors)
-                throw new Error(`GraphQL errors: ${JSON.stringify(data.errors)}`);
-            return data.data;
+            return gql(ctx, body);
         },
     });
     rl.registerAction("introspect", {
         access: "read",
         description: "Run an introspection query to get the schema",
         async execute(_input, ctx) {
-            const cfg = ctx.connection.config;
-            const endpoint = cfg.endpoint;
-            const hdrs = {
-                "Content-Type": "application/json",
-            };
-            if (cfg.headerAuth)
-                hdrs.Authorization = cfg.headerAuth;
-            if (cfg.headers) {
-                for (const [k, v] of Object.entries(cfg.headers)) {
-                    hdrs[k] = v;
-                }
-            }
             const introspectionQuery = `{
         __schema {
           types { name kind description fields { name type { name kind ofType { name kind } } } }
@@ -96,15 +79,7 @@ export default function graphql(rl) {
           subscriptionType { name }
         }
       }`;
-            const res = await fetch(endpoint, {
-                method: "POST",
-                headers: hdrs,
-                body: JSON.stringify({ query: introspectionQuery }),
-            });
-            if (!res.ok)
-                throw new Error(`GraphQL error ${res.status}: ${await res.text()}`);
-            const data = (await res.json());
-            return data.data;
+            return gql(ctx, { query: introspectionQuery });
         },
     });
 }

package/dist/plugins/grist/src/credentials.js

@@ -0,0 +1,30 @@
+import { configChoice, hostLabel, httpsBase, staticCredential, } from "../../_shared/credentials.js";
+/**
+ * An API key, sent as a bearer to the plan's one API origin: docs.getgrist.com
+ * (free), the team subdomain (paid), or the self-hosted instance.
+ */
+export const gristCredential = staticCredential({
+    id: "grist",
+    auth: { kind: "bearer" },
+    local: { secret: "apiKey" },
+    targets: (config) => {
+        const planType = configChoice(config.planType, ["free", "paid", "selfHosted"], "free");
+        const baseUrl = planType === "selfHosted"
+            ? httpsBase(config.selfHostedUrl, "api/")
+            : planType === "paid"
+                ? `https://${hostLabel(config.subdomain)}.getgrist.com/api/`
+                : "https://docs.getgrist.com/api/";
+        return {
+            api: {
+                baseUrl,
+                methods: ["GET", "POST", "PATCH"],
+            },
+        };
+    },
+    probe: {
+        target: "api",
+        path: "orgs",
+        method: "GET",
+        acceptedStatuses: [200],
+    },
+});

package/dist/plugins/grist/src/index.js

@@ -1,43 +1,18 @@
-async function apiRequest(baseUrl, apiKey, method, endpoint, body, qs) {
-    const url = new URL(`${baseUrl}/api${endpoint}`);
-    if (qs) {
-        for (const [k, v] of Object.entries(qs)) {
-            if (v !== undefined && v !== null)
-                url.searchParams.set(k, String(v));
-        }
-    }
-    const opts = {
+import { credentialJson, pathSegment } from "../../_shared/credentials.js";
+import { gristCredential } from "./credentials.js";
+function apiRequest(ctx, method, path, body, query) {
+    return credentialJson(ctx, gristCredential, "grist", {
+        target: "api",
+        path,
         method,
-        headers: {
-            Authorization: `Bearer ${apiKey}`,
-            "Content-Type": "application/json",
-        },
-    };
-    if (body !== undefined && method !== "GET" && method !== "DELETE") {
-        opts.body = JSON.stringify(body);
-    }
-    const res = await fetch(url.toString(), opts);
-    if (!res.ok)
-        throw new Error(`Grist API error ${res.status}: ${await res.text()}`);
-    if (res.status === 204)
-        return { success: true };
-    return res.json();
-}
-function getConn(ctx) {
-    const cfg = ctx.connection.config;
-    const planType = cfg.planType ?? "free";
-    let baseUrl;
-    if (planType === "selfHosted")
-        baseUrl = cfg.selfHostedUrl.replace(/\/$/, "");
-    else if (planType === "paid")
-        baseUrl = `https://${cfg.subdomain}.getgrist.com`;
-    else
-        baseUrl = "https://docs.getgrist.com";
-    return { baseUrl, apiKey: cfg.apiKey };
+        query,
+        ...(body !== undefined ? { json: body } : {}),
+    });
 }
 export default function grist(rl) {
     rl.setName("grist");
     rl.setVersion("0.1.0");
+    rl.setCredential(gristCredential);
     rl.setConnectionSchema({
         apiKey: {
             type: "string",
@@ -77,8 +52,7 @@ export default function grist(rl) {
         },
         async execute(input, ctx) {
             const { docId, tableId, records } = input;
-            const { baseUrl, apiKey } = getConn(ctx);
-            return apiRequest(baseUrl, apiKey, "POST", `/docs/${docId}/tables/${tableId}/records`, { records });
+            return apiRequest(ctx, "POST", `docs/${pathSegment(docId)}/tables/${pathSegment(tableId)}/records`, { records });
         },
     });
     rl.registerAction("record.list", {
@@ -101,7 +75,6 @@ export default function grist(rl) {
         },
         async execute(input, ctx) {
             const { docId, tableId, limit, sort, filter } = (input ?? {});
-            const { baseUrl, apiKey } = getConn(ctx);
             const qs = {};
             if (limit)
                 qs.limit = limit;
@@ -109,7 +82,7 @@ export default function grist(rl) {
                 qs.sort = sort;
             if (filter)
                 qs.filter = JSON.stringify(filter);
-            const data = (await apiRequest(baseUrl, apiKey, "GET", `/docs/${docId}/tables/${tableId}/records`, undefined, qs));
+            const data = (await apiRequest(ctx, "GET", `docs/${pathSegment(docId)}/tables/${pathSegment(tableId)}/records`, undefined, qs));
             return data.records;
         },
     });
@@ -127,8 +100,7 @@ export default function grist(rl) {
         },
         async execute(input, ctx) {
             const { docId, tableId, records } = input;
-            const { baseUrl, apiKey } = getConn(ctx);
-            return apiRequest(baseUrl, apiKey, "PATCH", `/docs/${docId}/tables/${tableId}/records`, { records });
+            return apiRequest(ctx, "PATCH", `docs/${pathSegment(docId)}/tables/${pathSegment(tableId)}/records`, { records });
         },
     });
     rl.registerAction("record.delete", {
@@ -145,8 +117,7 @@ export default function grist(rl) {
         },
         async execute(input, ctx) {
             const { docId, tableId, rowIds } = input;
-            const { baseUrl, apiKey } = getConn(ctx);
-            return apiRequest(baseUrl, apiKey, "POST", `/docs/${docId}/tables/${tableId}/data/delete`, rowIds);
+            return apiRequest(ctx, "POST", `docs/${pathSegment(docId)}/tables/${pathSegment(tableId)}/data/delete`, rowIds);
         },
     });
 }

package/dist/plugins/halopsa/src/credentials.js

@@ -0,0 +1,56 @@
+import { AuthError, } from "runline";
+import { configChoice, grantSchema, httpsBase, } from "../../_shared/credentials.js";
+/**
+ * A client-credentials OAuth grant: the token comes from the configured
+ * auth server (cloud, optionally tenant-qualified) or the on-premise app's
+ * /auth/token, and signs as a bearer against the configured resource API
+ * base. Every URL is public config and must be HTTPS.
+ */
+export const halopsaCredential = (config) => {
+    let tokenUrl = configChoice(config.hostingType, ["cloud", "on-premise"], "cloud") ===
+        "on-premise"
+        ? httpsBase(config.appUrl, "auth/token")
+        : httpsBase(config.authUrl, "token");
+    if (config.tenant !== undefined) {
+        if (typeof config.tenant !== "string" || !config.tenant)
+            throw new AuthError("invalid_credentials");
+        tokenUrl += `?tenant=${encodeURIComponent(config.tenant)}`;
+    }
+    const scope = typeof config.scope === "string" && config.scope ? config.scope : "all";
+    const type = {
+        id: "halopsa",
+        methods: {
+            oauth2: {
+                schema: grantSchema,
+                authentication: {
+                    kind: "oauth2",
+                    field: "grant",
+                    renewal: "clientCredentials",
+                    definition: {
+                        id: "halopsa.oauth2",
+                        provider: "halopsa",
+                        clientCredentials: {
+                            url: tokenUrl,
+                            clientAuthentication: "client_secret_post",
+                        },
+                    },
+                    scopes: [scope],
+                },
+                targets: {
+                    api: {
+                        baseUrl: httpsBase(config.resourceApiUrl, ""),
+                        methods: ["GET", "POST", "PUT", "DELETE"],
+                    },
+                },
+            },
+        },
+    };
+    return {
+        type,
+        method: "oauth2",
+        application: {
+            clientId: config.clientId,
+            clientSecret: config.clientSecret,
+        },
+    };
+};

package/dist/plugins/halopsa/src/index.js

@@ -1,47 +1,19 @@
-import { coordinatedAccessToken, requestToken, } from "../../_shared/tokenRefresh.js";
-async function apiRequest(apiUrl, token, method, endpoint, body, qs) {
-    const url = new URL(`${apiUrl}${endpoint}`);
-    if (qs) {
-        for (const [k, v] of Object.entries(qs)) {
-            if (v !== undefined && v !== null)
-                url.searchParams.set(k, String(v));
-        }
-    }
-    const opts = {
-        method,
-        headers: {
-            Authorization: `Bearer ${token}`,
-            "Content-Type": "application/json",
-        },
-    };
-    if (body &&
+import { credentialJson, pathSegment } from "../../_shared/credentials.js";
+import { halopsaCredential } from "./credentials.js";
+function req(ctx, method, path, body, qs) {
+    const json = body &&
         Object.keys(body).length > 0 &&
         method !== "GET" &&
-        method !== "DELETE")
-        opts.body = JSON.stringify(body);
-    const res = await fetch(url.toString(), opts);
-    if (!res.ok)
-        throw new Error(`HaloPSA API error ${res.status}: ${await res.text()}`);
-    if (res.status === 204)
-        return { success: true };
-    return res.json();
-}
-async function req(ctx, method, endpoint, body, qs) {
-    const token = await coordinatedAccessToken(ctx, (cfg) => {
-        const url = new URL(cfg.hostingType === "on-premise"
-            ? `${cfg.appUrl}/auth/token`
-            : `${cfg.authUrl}/token`);
-        if (cfg.tenant)
-            url.searchParams.set("tenant", cfg.tenant);
-        return requestToken({ url: url.toString(), clientAuthentication: "client_secret_post" }, {
-            grant_type: "client_credentials",
-            scope: cfg.scope ?? "all",
-        }, {
-            clientId: cfg.clientId,
-            clientSecret: cfg.clientSecret,
-        });
+        method !== "DELETE"
+        ? body
+        : undefined;
+    return credentialJson(ctx, halopsaCredential, "halopsa", {
+        target: "api",
+        path,
+        method,
+        query: qs,
+        ...(json !== undefined ? { json } : {}),
     });
-    return apiRequest(ctx.connection.config.resourceApiUrl.replace(/\/$/, ""), token, method, endpoint, body, qs);
 }
 function registerCrud(rl, resource, apiPath) {
     rl.registerAction(`${resource}.create`, {
@@ -67,7 +39,7 @@ function registerCrud(rl, resource, apiPath) {
             id: { type: "number", required: true, description: `${resource} ID` },
         },
         async execute(input, ctx) {
-            return req(ctx, "GET", `${apiPath}/${input.id}`);
+            return req(ctx, "GET", `${apiPath}/${pathSegment(input.id)}`);
         },
     });
     rl.registerAction(`${resource}.list`, {
@@ -110,7 +82,7 @@ function registerCrud(rl, resource, apiPath) {
             id: { type: "number", required: true, description: `${resource} ID` },
         },
         async execute(input, ctx) {
-            await req(ctx, "DELETE", `${apiPath}/${input.id}`);
+            await req(ctx, "DELETE", `${apiPath}/${pathSegment(input.id)}`);
             return { success: true };
         },
     });
@@ -118,6 +90,7 @@ function registerCrud(rl, resource, apiPath) {
 export default function halopsa(rl) {
     rl.setName("halopsa");
     rl.setVersion("0.1.0");
+    rl.setCredential(halopsaCredential);
     rl.setConnectionSchema({
         hostingType: {
             type: "string",
@@ -167,8 +140,8 @@ export default function halopsa(rl) {
             description: "Tenant (cloud only)",
         },
     });
-    registerCrud(rl, "client", "/client");
-    registerCrud(rl, "site", "/site");
-    registerCrud(rl, "ticket", "/tickets");
-    registerCrud(rl, "user", "/users");
+    registerCrud(rl, "client", "client");
+    registerCrud(rl, "site", "site");
+    registerCrud(rl, "ticket", "tickets");
+    registerCrud(rl, "user", "users");
 }

package/dist/plugins/harvest/src/credentials.js

@@ -0,0 +1,20 @@
+import { staticCredential } from "../../_shared/credentials.js";
+/**
+ * A personal access token, sent as a bearer to Harvest's one API origin.
+ * Every request also carries the public Harvest-Account-Id companion
+ * header and Harvest's required User-Agent.
+ */
+export const harvestCredential = staticCredential({
+    id: "harvest",
+    auth: { kind: "bearer" },
+    local: { secret: "token" },
+    targets: {
+        api: {
+            baseUrl: "https://api.harvestapp.com/v2/",
+            methods: ["GET", "POST", "PATCH", "DELETE"],
+            allowedHeaders: ["Harvest-Account-Id", "User-Agent"],
+        },
+    },
+    // No probe: every accepted request needs the Harvest-Account-Id header,
+    // which a fixed probe cannot carry.
+});

package/dist/plugins/harvest/src/index.js

@@ -1,42 +1,22 @@
-const BASE_URL = "https://api.harvestapp.com/v2";
-async function apiRequest(token, accountId, method, endpoint, body, qs) {
-    const url = new URL(`${BASE_URL}/${endpoint}`);
-    if (qs) {
-        for (const [k, v] of Object.entries(qs)) {
-            if (v !== undefined && v !== null)
-                url.searchParams.set(k, String(v));
-        }
-    }
-    const opts = {
+import { credentialJson, pathSegment } from "../../_shared/credentials.js";
+import { harvestCredential } from "./credentials.js";
+function hv(ctx, method, path, body, qs) {
+    return credentialJson(ctx, harvestCredential, "harvest", {
+        target: "api",
+        path,
         method,
+        query: qs,
         headers: {
-            Authorization: `Bearer ${token}`,
-            "Harvest-Account-Id": accountId,
-            "Content-Type": "application/json",
+            "Harvest-Account-Id": String(ctx.connection.config.accountId),
             "User-Agent": "Runline",
         },
-    };
-    if (body &&
-        Object.keys(body).length > 0 &&
-        method !== "GET" &&
-        method !== "DELETE")
-        opts.body = JSON.stringify(body);
-    const res = await fetch(url.toString(), opts);
-    if (!res.ok)
-        throw new Error(`Harvest API error ${res.status}: ${await res.text()}`);
-    if (res.status === 204)
-        return { success: true };
-    return res.json();
-}
-function getConn(ctx) {
-    return {
-        token: ctx.connection.config.token,
-        accountId: ctx.connection.config.accountId,
-    };
-}
-function hv(ctx, method, endpoint, body, qs) {
-    const { token, accountId } = getConn(ctx);
-    return apiRequest(token, accountId, method, endpoint, body, qs);
+        ...(body &&
+            Object.keys(body).length > 0 &&
+            method !== "GET" &&
+            method !== "DELETE"
+            ? { json: body }
+            : {}),
+    });
 }
 function unwrapList(data, key) {
     if (data &&
@@ -67,7 +47,7 @@ function registerCrud(rl, resource, apiPath, listKey) {
             id: { type: "number", required: true, description: `${resource} ID` },
         },
         async execute(input, ctx) {
-            return hv(ctx, "GET", `${apiPath}/${input.id}`);
+            return hv(ctx, "GET", `${apiPath}/${pathSegment(input.id)}`);
         },
     });
     rl.registerAction(`${resource}.list`, {
@@ -100,7 +80,7 @@ function registerCrud(rl, resource, apiPath, listKey) {
         },
         async execute(input, ctx) {
             const { id, properties } = input;
-            return hv(ctx, "PATCH", `${apiPath}/${id}`, properties);
+            return hv(ctx, "PATCH", `${apiPath}/${pathSegment(id)}`, properties);
         },
     });
     rl.registerAction(`${resource}.delete`, {
@@ -110,7 +90,7 @@ function registerCrud(rl, resource, apiPath, listKey) {
             id: { type: "number", required: true, description: `${resource} ID` },
         },
         async execute(input, ctx) {
-            await hv(ctx, "DELETE", `${apiPath}/${input.id}`);
+            await hv(ctx, "DELETE", `${apiPath}/${pathSegment(input.id)}`);
             return { success: true };
         },
     });
@@ -118,6 +98,7 @@ function registerCrud(rl, resource, apiPath, listKey) {
 export default function harvest(rl) {
     rl.setName("harvest");
     rl.setVersion("0.1.0");
+    rl.setCredential(harvestCredential);
     rl.setConnectionSchema({
         token: {
             type: "string",
@@ -210,7 +191,7 @@ export default function harvest(rl) {
             id: { type: "number", required: true, description: "Time entry ID" },
         },
         async execute(input, ctx) {
-            return hv(ctx, "GET", `time_entries/${input.id}`);
+            return hv(ctx, "GET", `time_entries/${pathSegment(input.id)}`);
         },
     });
     rl.registerAction("timeEntry.list", {
@@ -272,7 +253,7 @@ export default function harvest(rl) {
         },
         async execute(input, ctx) {
             const { id, properties } = input;
-            return hv(ctx, "PATCH", `time_entries/${id}`, properties);
+            return hv(ctx, "PATCH", `time_entries/${pathSegment(id)}`, properties);
         },
     });
     rl.registerAction("timeEntry.delete", {
@@ -282,7 +263,7 @@ export default function harvest(rl) {
             id: { type: "number", required: true, description: "Time entry ID" },
         },
         async execute(input, ctx) {
-            await hv(ctx, "DELETE", `time_entries/${input.id}`);
+            await hv(ctx, "DELETE", `time_entries/${pathSegment(input.id)}`);
             return { success: true };
         },
     });
@@ -293,7 +274,7 @@ export default function harvest(rl) {
             id: { type: "number", required: true, description: "Time entry ID" },
         },
         async execute(input, ctx) {
-            return hv(ctx, "PATCH", `time_entries/${input.id}/restart`);
+            return hv(ctx, "PATCH", `time_entries/${pathSegment(input.id)}/restart`);
         },
     });
     rl.registerAction("timeEntry.stop", {
@@ -303,7 +284,7 @@ export default function harvest(rl) {
             id: { type: "number", required: true, description: "Time entry ID" },
         },
         async execute(input, ctx) {
-            return hv(ctx, "PATCH", `time_entries/${input.id}/stop`);
+            return hv(ctx, "PATCH", `time_entries/${pathSegment(input.id)}/stop`);
         },
     });
     // Company (read-only)

package/dist/plugins/helpscout/src/credentials.js

@@ -0,0 +1,13 @@
+import { staticCredential } from "../../_shared/credentials.js";
+/** An OAuth2 app access token, sent as a bearer to Help Scout's v2 API. */
+export const helpscoutCredential = staticCredential({
+    id: "helpscout",
+    auth: { kind: "bearer" },
+    local: { secret: "accessToken" },
+    targets: {
+        api: {
+            baseUrl: "https://api.helpscout.net/v2/",
+            methods: ["GET", "POST", "PUT", "DELETE"],
+        },
+    },
+});