@airfone/connector 0.0.0-stage → 0.1.0

package/dist/review.js

@@ -0,0 +1,103 @@
+// The checks AirFone runs on upload (service.rs review()), run locally.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { buildRequest } from './http.js';
+import { checkSchema, secretNames, withConfigDefaults } from './manifest.js';
+import { ReviewHost } from './host.js';
+import { compileCheck, runAction } from './runner.js';
+export function subset(expected, actual) {
+    if (expected && actual && typeof expected === 'object' && typeof actual === 'object' && !Array.isArray(expected) && !Array.isArray(actual)) {
+        return Object.entries(expected).every(([k, v]) => k in actual && subset(v, actual[k]));
+    }
+    return JSON.stringify(expected) === JSON.stringify(actual);
+}
+/** Fixtures from the manifest, plus tests/*.json files ({ action, input, config?, expect? } or an array of them). These run locally only. */
+export function fixtures(m, dir) {
+    const out = [];
+    for (const a of m.actions)
+        (a.fixtures ?? []).forEach((f, i) => out.push({ action: a.name, label: `${a.name} fixture ${i + 1}`, input: f.input, config: f.config, expect: f.expect }));
+    const testDir = join(dir, 'tests');
+    if (existsSync(testDir)) {
+        for (const file of readdirSync(testDir).filter((f) => f.endsWith('.json')).sort()) {
+            const data = JSON.parse(readFileSync(join(testDir, file), 'utf8'));
+            (Array.isArray(data) ? data : [data]).forEach((f, i) => out.push({ ...f, label: `tests/${file}${Array.isArray(data) ? ` #${i + 1}` : ''} (${f.action})` }));
+        }
+    }
+    return out;
+}
+export async function review(m, js, list) {
+    const findings = [];
+    const error = (message) => findings.push({ level: 'error', message });
+    const warning = (message) => findings.push({ level: 'warning', message });
+    if (m.sensitive)
+        warning(`sensitive: hosts in ${(m.regions ?? []).join(', ')}`);
+    if (m.actions.some((a) => a.kind === 'js') && js === null) {
+        error('the manifest has JS actions but the bundle has no index.js');
+        return findings;
+    }
+    if (js !== null) {
+        if (Buffer.byteLength(js) > 1024 * 1024)
+            error('index.js is over 1 MB');
+        for (const banned of ['eval(', 'new Function(', 'Function("', '__proto__', 'WebAssembly'])
+            if (js.includes(banned))
+                error(`index.js uses ${banned}, which is not allowed`);
+        for (const leak of ['-----BEGIN', 'sk_live_', 'AKIA', 'AIza', 'xoxb-', 'ghp_'])
+            if (js.includes(leak))
+                error(`index.js looks like it holds a credential (${leak}…); put it in secrets`);
+        try {
+            await compileCheck(js);
+        }
+        catch (e) {
+            error(`index.js does not load: ${e.message}`);
+            return findings;
+        }
+    }
+    const fakeSecrets = {};
+    for (const name of secretNames(m))
+        fakeSecrets[name] = 'review';
+    for (const f of list) {
+        const action = m.actions.find((x) => x.name === f.action);
+        if (!action) {
+            error(`${f.label}: no action named ${JSON.stringify(f.action)}`);
+            continue;
+        }
+        const config = withConfigDefaults(m.config, f.config ?? {});
+        try {
+            checkSchema('input', action.input, f.input);
+        }
+        catch (e) {
+            error(`${f.label}: ${e.message}`);
+            continue;
+        }
+        if (action.kind === 'http') {
+            try {
+                buildRequest(m, action.http, f.input, config, fakeSecrets);
+            }
+            catch (e) {
+                error(`${f.label}: ${e.message}`);
+            }
+            continue;
+        }
+        if (js === null)
+            continue;
+        try {
+            const out = await runAction(js, action.js ?? action.name, f.input, config, new ReviewHost(m, config));
+            try {
+                checkSchema('output', action.output, out);
+            }
+            catch (e) {
+                error(`${f.label}: ${e.message}`);
+                continue;
+            }
+            if (f.expect !== undefined && f.expect !== null && !subset(f.expect, out))
+                error(`${f.label}: expected ${JSON.stringify(f.expect)}, got ${JSON.stringify(out)}`);
+        }
+        catch (e) {
+            error(`${f.label}: ${e.message}`);
+        }
+    }
+    // AirFone only sees fixtures in manifest.json; tests/*.json stay on your machine.
+    if (!m.actions.some((x) => (x.fixtures ?? []).length > 0))
+        warning('no test fixtures: actions were checked but not run');
+    return findings;
+}

package/dist/runner.d.ts

@@ -0,0 +1,26 @@
+import { type QuickJSContext } from 'quickjs-emscripten';
+import type { OutRequest, OutResponse, EgressOptions } from './net.js';
+export interface Limits {
+    memoryBytes: number;
+    stackBytes: number;
+    cpuMs: number;
+    wallMs: number;
+}
+export declare const DEFAULT_LIMITS: Limits;
+/** Top-level module code at compile time (QuickJsEngine::default compile_limits). */
+export declare const COMPILE_LIMITS: Limits;
+/** The only way out of the sandbox. Throw a string or Error to fail the call. */
+export interface HostBridge {
+    call(op: string, args: any, deadline: number): unknown;
+}
+export declare const PRELUDE: string;
+export declare class ScriptError extends Error {
+}
+/** Compiles and evaluates index.js and checks it exports `actions`, as the server does on upload. */
+export declare function compileCheck(source: string): Promise<void>;
+/** Runs one action to completion. Resolves to the JSON result. */
+export declare function runAction(source: string, exportName: string, input: unknown, config: unknown, host: HostBridge, limits?: Limits): Promise<unknown>;
+export type { QuickJSContext };
+/** Sends an HTTP request and blocks until it answers or the deadline passes. */
+export declare function fetchSync(allowed: string[], req: OutRequest, opts: EgressOptions, deadline: number): OutResponse;
+export declare function stopHttpWorker(): void;

package/dist/runner.js

@@ -0,0 +1,280 @@
+// The local JS sandbox. It mirrors the server's QuickJS runtime
+// (backend/crates/connectors/src/js.rs) so code that works here works there:
+//
+// - QuickJS (via quickjs-emscripten), a fresh runtime and context per call;
+// - 64 MB heap, 512 KB stack, 2 s of CPU and 10 s of wall time per call
+//   (CPU = wall time minus time spent in host calls);
+// - the same PRELUDE: a frozen `ctx` whose host calls are synchronous inside
+//   the sandbox. Here http.fetch blocks on a worker thread with Atomics.wait,
+//   as the server blocks its sandbox thread;
+// - no timers, no global fetch, no filesystem.
+import { Worker, MessageChannel, receiveMessageOnPort } from 'node:worker_threads';
+import { getQuickJS } from 'quickjs-emscripten';
+export const DEFAULT_LIMITS = { memoryBytes: 64 * 1024 * 1024, stackBytes: 512 * 1024, cpuMs: 2000, wallMs: 10_000 };
+/** Top-level module code at compile time (QuickJsEngine::default compile_limits). */
+export const COMPILE_LIMITS = { memoryBytes: 32 * 1024 * 1024, stackBytes: 512 * 1024, cpuMs: 1000, wallMs: 1000 };
+// The ctx part of prelude.js. Keep identical.
+export const PRELUDE = String.raw `
+(() => {
+  const call = globalThis.__host;
+  const configJson = globalThis.__config;
+  delete globalThis.__host;
+  delete globalThis.__config;
+  const invoke = (op, args) => {
+    const r = JSON.parse(call(op, JSON.stringify(args === undefined ? null : args)));
+    if (!r.ok) throw new Error(r.error);
+    return r.value;
+  };
+  const freeze = Object.freeze;
+  const deepFreeze = (o) => {
+    if (o && typeof o === "object") { Object.values(o).forEach(deepFreeze); freeze(o); }
+    return o;
+  };
+  const fetch = (url, opts) => {
+    const o = opts || {};
+    const headers = Object.assign({}, o.headers || {});
+    let body = null;
+    if (o.json !== undefined) {
+      body = JSON.stringify(o.json);
+      if (!Object.keys(headers).some((k) => k.toLowerCase() === "content-type")) headers["Content-Type"] = "application/json";
+    } else if (o.body !== undefined && o.body !== null) {
+      body = typeof o.body === "string" ? o.body : JSON.stringify(o.body);
+    }
+    const r = invoke("http.fetch", {
+      url: String(url), method: o.method || "GET", headers, query: o.query || {}, body,
+    });
+    let json = null;
+    try { json = r.body === "" ? null : JSON.parse(r.body); } catch (e) { json = null; }
+    return freeze({
+      status: r.status, ok: r.status >= 200 && r.status < 300, headers: freeze(r.headers),
+      text: r.body, json: deepFreeze(json),
+    });
+  };
+  const logAt = (level) => (message, fields) => {
+    const text = typeof message === "string" ? message : JSON.stringify(message);
+    invoke("log", { level, message: fields === undefined ? text : text + " " + JSON.stringify(fields) });
+  };
+  const log = (...parts) => {
+    invoke("log", { level: "info", message: parts.map((x) => typeof x === "string" ? x : JSON.stringify(x)).join(" ") });
+  };
+  log.info = logAt("info"); log.warn = logAt("warn"); log.error = logAt("error");
+  freeze(log);
+  Object.defineProperty(globalThis, "__ctx", { value: freeze({
+    config: deepFreeze(JSON.parse(configJson)),
+    http: freeze({ fetch }),
+    store: freeze({
+      get: (key) => invoke("store.get", { key: String(key) }),
+      set: (key, value, opts) => {
+        const args = { key: String(key), value: value === undefined ? null : value };
+        if (opts && Object.prototype.hasOwnProperty.call(opts, "ifEquals")) {
+          args.if_equals = opts.ifEquals === undefined ? null : opts.ifEquals;
+          return invoke("store.set", args);
+        }
+        invoke("store.set", args);
+      },
+      incr: (key, by) => invoke("store.incr", { key: String(key), by: by === undefined ? 1 : Number(by) }),
+      delete: (key) => { invoke("store.delete", { key: String(key) }); },
+    }),
+    records: freeze({ upsert: (records) => invoke("records.upsert", { records }) }),
+    // The workspace's knowledge (the Brain): records upserted by external_id,
+    // only with the knowledge.write scope.
+    knowledge: freeze({
+      upsert: (records) => invoke("knowledge.upsert", { records }),
+      delete: (externalId) => invoke("knowledge.delete", { external_id: String(externalId) }),
+    }),
+    crypto: freeze({
+      hmac: (alg, secretName, message, encoding) =>
+        invoke("crypto.hmac", { alg: String(alg), secret: String(secretName), message: String(message), encoding: encoding || "hex" }),
+      sha256: (message, encoding) => invoke("crypto.hash", { alg: "sha256", message: String(message), encoding: encoding || "hex" }),
+      hash: (alg, message, encoding) => invoke("crypto.hash", { alg: String(alg), message: String(message), encoding: encoding || "hex" }),
+    }),
+    log,
+  }), enumerable: false, writable: false, configurable: false });
+})();
+`;
+export class ScriptError extends Error {
+}
+let quickjs = null;
+async function engine() { return (quickjs ??= await getQuickJS()); }
+const STOP_NONE = 0, STOP_CPU = 1, STOP_WALL = 2;
+/** Compiles and evaluates index.js and checks it exports `actions`, as the server does on upload. */
+export async function compileCheck(source) {
+    await run(source, null, null, {}, { call: () => { throw 'no host calls while the module loads'; } }, COMPILE_LIMITS);
+}
+/** Runs one action to completion. Resolves to the JSON result. */
+export async function runAction(source, exportName, input, config, host, limits = DEFAULT_LIMITS) {
+    return run(source, exportName, input, config, host, limits);
+}
+async function run(source, exportName, input, config, host, limits) {
+    const QuickJS = await engine();
+    const rt = QuickJS.newRuntime();
+    rt.setMemoryLimit(limits.memoryBytes);
+    rt.setMaxStackSize(limits.stackBytes);
+    const start = performance.now();
+    const deadline = Date.now() + limits.wallMs;
+    let hostMs = 0;
+    let stop = STOP_NONE;
+    rt.setInterruptHandler(() => {
+        const elapsed = performance.now() - start;
+        if (elapsed >= limits.wallMs) {
+            stop = STOP_WALL;
+            return true;
+        }
+        if (elapsed - hostMs >= limits.cpuMs) {
+            stop = STOP_CPU;
+            return true;
+        }
+        return false;
+    });
+    const ctx = rt.newContext();
+    const handles = [];
+    const keep = (h) => { handles.push(h); return h; };
+    const fail = (raw) => {
+        if (stop === STOP_CPU)
+            return new ScriptError(`stopped: used more than ${limits.cpuMs / 1000}s of CPU`);
+        if (stop === STOP_WALL)
+            return new ScriptError(`stopped: ran longer than ${limits.wallMs / 1000}s`);
+        const detail = typeof raw === 'object' && raw && 'message' in raw ? String(raw.message) : String(raw ?? 'exception');
+        if (/out of memory/i.test(detail))
+            return new ScriptError(`stopped: used more than ${limits.memoryBytes / (1024 * 1024)} MB of memory`);
+        if (/stack overflow/i.test(detail))
+            return new ScriptError('stopped: stack overflow');
+        return new ScriptError(detail);
+    };
+    const unwrap = (r) => {
+        if (r.error) {
+            const e = ctx.dump(r.error);
+            r.error.dispose();
+            throw fail(e);
+        }
+        return keep(r.value);
+    };
+    const settle = (h) => {
+        for (;;) {
+            const state = ctx.getPromiseState(h);
+            if (state.type === 'fulfilled')
+                return state.notAPromise ? h : keep(state.value);
+            if (state.type === 'rejected') {
+                const e = ctx.dump(state.error);
+                state.error.dispose();
+                throw fail(e);
+            }
+            const jobs = rt.executePendingJobs();
+            if (jobs.error) {
+                const e = ctx.dump(jobs.error);
+                jobs.error.dispose();
+                throw fail(e);
+            }
+            if (jobs.value === 0) {
+                const again = ctx.getPromiseState(h);
+                if (again.type === 'pending')
+                    throw new ScriptError('the action never finished (waiting on something that cannot happen here)');
+            }
+        }
+    };
+    try {
+        const bridge = keep(ctx.newFunction('__host', (opH, argsH) => {
+            const began = performance.now();
+            let reply;
+            try {
+                if (Date.now() >= deadline)
+                    throw 'out of time';
+                const value = host.call(ctx.getString(opH), JSON.parse(ctx.getString(argsH)), deadline);
+                reply = { ok: true, value: value === undefined ? null : value };
+            }
+            catch (e) {
+                reply = { ok: false, error: e instanceof Error ? e.message : String(e) };
+            }
+            hostMs += performance.now() - began;
+            return ctx.newString(JSON.stringify(reply));
+        }));
+        ctx.setProp(ctx.global, '__host', bridge);
+        ctx.setProp(ctx.global, '__config', keep(ctx.newString(JSON.stringify(config ?? {}))));
+        unwrap(ctx.evalCode(PRELUDE, 'prelude.js'));
+        const ns = settle(unwrap(ctx.evalCode(source, 'connector', { type: 'module' })));
+        const actions = keep(ctx.getProp(ns, 'actions'));
+        if (ctx.typeof(actions) !== 'object' && ctx.typeof(actions) !== 'function')
+            throw new ScriptError('index.js must `export const actions = { ... }`');
+        if (exportName === null)
+            return null;
+        const fn = keep(ctx.getProp(actions, exportName));
+        if (ctx.typeof(fn) !== 'function')
+            throw new ScriptError(`index.js does not export action ${JSON.stringify(exportName)}`);
+        ctx.setProp(ctx.global, '__input', keep(ctx.newString(JSON.stringify(input ?? null))));
+        const inputH = unwrap(ctx.evalCode('JSON.parse(globalThis.__input)', 'input.js'));
+        const ctxH = keep(ctx.getProp(ctx.global, '__ctx'));
+        const ret = settle(unwrap(ctx.callFunction(fn, ctx.undefined, inputH, ctxH)));
+        if (ctx.typeof(ret) === 'undefined')
+            return null;
+        ctx.setProp(ctx.global, '__ret', ret);
+        const text = unwrap(ctx.evalCode('JSON.stringify(globalThis.__ret)', 'ret.js'));
+        const s = ctx.typeof(text) === 'string' ? ctx.getString(text) : 'null';
+        try {
+            return JSON.parse(s);
+        }
+        catch (e) {
+            throw new ScriptError(`the action returned non-JSON: ${e.message}`);
+        }
+    }
+    catch (e) {
+        if (e instanceof ScriptError)
+            throw e;
+        throw fail(e);
+    }
+    finally {
+        for (const h of handles.reverse()) {
+            try {
+                if (h.alive)
+                    h.dispose();
+            }
+            catch { /* already gone */ }
+        }
+        try {
+            ctx.dispose();
+        }
+        catch { /* leaked handle after a stop */ }
+        try {
+            rt.dispose();
+        }
+        catch { /* same */ }
+    }
+}
+// ---- Synchronous HTTP for the sandbox ----------------------------------
+const WORKER = `
+const { parentPort, workerData } = require('node:worker_threads');
+import(workerData.net).then(({ send }) => {
+  parentPort.on('message', async ({ port, allowed, req, opts, flag }) => {
+    let msg;
+    try { msg = { ok: true, value: await send(allowed, req, opts) }; } catch (e) { msg = { ok: false, error: e.message }; }
+    port.postMessage(msg);
+    const i32 = new Int32Array(flag);
+    Atomics.store(i32, 0, 1);
+    Atomics.notify(i32, 0);
+  });
+});
+`;
+let worker = null;
+function httpWorker() {
+    if (!worker) {
+        worker = new Worker(WORKER, { eval: true, workerData: { net: new URL('./net.js', import.meta.url).href } });
+        worker.unref();
+    }
+    return worker;
+}
+/** Sends an HTTP request and blocks until it answers or the deadline passes. */
+export function fetchSync(allowed, req, opts, deadline) {
+    const flag = new SharedArrayBuffer(4);
+    const { port1, port2 } = new MessageChannel();
+    httpWorker().postMessage({ port: port2, allowed, req, opts, flag }, [port2]);
+    const left = deadline - Date.now();
+    const r = Atomics.wait(new Int32Array(flag), 0, 0, Math.max(0, left));
+    const got = receiveMessageOnPort(port1);
+    port1.close();
+    if (r === 'timed-out' || !got)
+        throw new Error('out of time');
+    const msg = got.message;
+    if (!msg.ok)
+        throw new Error(msg.error);
+    return msg.value;
+}
+export function stopHttpWorker() { void worker?.terminate(); worker = null; }

package/dist/types.d.ts

@@ -0,0 +1,228 @@
+/** A JSON Schema object (draft 2020-12). */
+export type JsonSchema = {
+    [key: string]: unknown;
+};
+export type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+export type Scope = 'records.read' | 'records.write' | 'contacts.read' | 'messages.send';
+export type Risk = 'read' | 'change' | 'money';
+export type Confirm = 'none' | 'caller' | 'staff';
+/**
+ * How AirFone authenticates to your hosts. Secrets come from the install's
+ * encrypted secrets and are added by AirFone to every request to a declared
+ * host. Your code never sees them.
+ *
+ * `type` and `kind` are the same field; `type` is the documented spelling.
+ */
+export type Auth = {
+    type?: 'none';
+    kind?: 'none';
+} | {
+    type?: 'api_key';
+    kind?: 'api_key';
+    header?: string;
+    query?: string;
+    name?: string;
+    in?: 'header' | 'query';
+    secret?: string;
+    prefix?: string;
+} | {
+    type?: 'bearer';
+    kind?: 'bearer';
+    secret?: string;
+} | {
+    type?: 'basic';
+    kind?: 'basic';
+    username?: string;
+    password?: string;
+} | {
+    type?: 'oauth';
+    kind?: 'oauth';
+    secret?: string;
+    scopes?: string[];
+    authorize_url?: string;
+    token_url?: string;
+    prefix?: string;
+};
+/**
+ * A declarative HTTP request. Strings are templates: `{{input.x}}`, `{{config.y}}`;
+ * `{{secrets.z}}` only in headers and query. `{{a ?? b}}` takes the first value that is
+ * not missing, null or "". Filters: `{{x | base64}}`, `urlencode`, `sha256`,
+ * `hmac_sha256(secret_name)` (hex), `hmac_sha256_b64(secret_name)`.
+ */
+export interface HttpSpec {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | Lowercase<'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'>;
+    /** `https://<declared host>/...` or `{{config.<field>}}/...`. */
+    url: string;
+    query?: Record<string, string>;
+    headers?: Record<string, string>;
+    /** A JSON value whose strings are templates. A string that is exactly one `{{...}}` keeps the value's JSON type. */
+    body?: Json;
+    /** Output field to JSONPath into the response body. Empty: the whole body. `map` is accepted too. */
+    output?: Record<string, string>;
+    map?: Record<string, string>;
+    /** HTTP status to a message the assistant can say. */
+    errors?: Record<string, string>;
+    /** Fail a 2xx answer whose JSON matches. Checked in order. */
+    fail_when?: FailRule[];
+}
+/**
+ * Fails the call when `path` (JSONPath) finds `equals`, or with no `equals`
+ * when it finds any non-null value. The message is `message`, else the value
+ * at `message_path`, else a generic one.
+ */
+export interface FailRule {
+    path: string;
+    equals?: Json;
+    message?: string;
+    message_path?: string;
+}
+/** An extra install secret, for signing keys and the like. */
+export interface SecretSpec {
+    /** Letters, digits and _. */
+    name: string;
+    title?: string;
+    description?: string;
+}
+/** A recorded call used by `airfone connector test` and by AirFone's review. */
+export interface Fixture {
+    input: Json;
+    config?: Json;
+    /** Subset match against the output. */
+    expect?: Json;
+}
+export interface Action {
+    /** Lowercase words joined by dots, like `order.create`. */
+    name: string;
+    /** Shown to the AI. */
+    description: string;
+    input: JsonSchema;
+    output: JsonSchema;
+    risk: Risk;
+    /** Required (`caller` or `staff`) when risk is `money`. */
+    confirm?: Confirm;
+    /** Inferred from `http` or `js` when left out. */
+    kind?: 'http' | 'js';
+    http?: HttpSpec;
+    /** For a JS action: the export in `actions` to call. Defaults to `name`. */
+    js?: string;
+    fixtures?: Fixture[];
+    /** Seconds a successful run may answer the same input again (pure reads only, 0 to 300; default 0). */
+    cache_seconds?: number;
+}
+export interface Manifest {
+    /** Lowercase reverse DNS, like `np.daraz.seller`. */
+    id: string;
+    /** Semver. */
+    version: string;
+    name: string;
+    description?: string;
+    category?: string;
+    sensitive?: boolean;
+    /** Countries your hosts are in. Required when sensitive. */
+    regions?: string[];
+    auth?: Auth;
+    /** Secrets beyond the ones `auth` names. */
+    secrets?: SecretSpec[];
+    /** JSON Schema for the install's settings form. A property's `default` fills a missing value. */
+    config?: JsonSchema;
+    permissions?: {
+        /** `api.example.com`, `*.example.com`, or `{{config.store_url}}`. */
+        hosts?: string[];
+        /** `records:write` is accepted for `records.write`. */
+        scopes?: (Scope | 'records:read' | 'records:write' | 'contacts:read' | 'messages:send')[];
+    };
+    actions: Action[];
+    knowledge?: {
+        name: string;
+        description?: string;
+        action: string;
+        schedule?: string;
+    }[];
+    triggers?: {
+        name: string;
+        description?: string;
+        source: 'webhook' | 'schedule';
+    }[];
+    ui?: {
+        /** Stable id the host routes by. */
+        name: string;
+        title?: string;
+        placement: 'main' | 'contact' | 'inbox';
+        /** Path under ui/. */
+        entry: string;
+        /** Bridge calls the panel may make. */
+        bridge_apis?: ('auth.session' | 'ui.toast' | 'ui.resize' | 'nav.open' | 'contact.current')[];
+    }[];
+}
+export interface FetchOptions {
+    method?: string;
+    headers?: Record<string, string>;
+    query?: Record<string, string | number | boolean>;
+    /** Sent as JSON with `Content-Type: application/json`. */
+    json?: Json;
+    /** A string, or a value that is JSON encoded. */
+    body?: string | Json;
+}
+export interface FetchResponse {
+    status: number;
+    ok: boolean;
+    headers: Readonly<Record<string, string>>;
+    /** The body as text. */
+    text: string;
+    /** The body parsed as JSON, or null. */
+    json: any;
+}
+export interface Log {
+    (...parts: unknown[]): void;
+    info(message: unknown, fields?: unknown): void;
+    warn(message: unknown, fields?: unknown): void;
+    error(message: unknown, fields?: unknown): void;
+}
+/**
+ * The second argument of every JS action. Host calls are synchronous inside
+ * the sandbox: they return values, not promises, so `await` works and so
+ * does plain use. There are no timers, no global `fetch` and no filesystem.
+ */
+export interface Ctx<Config = Record<string, any>> {
+    /** The install's settings, read only. Secrets are not included. */
+    readonly config: Readonly<Config>;
+    readonly http: {
+        fetch(url: string, options?: FetchOptions): FetchResponse;
+    };
+    /** A small key-value store per install. Keys 1 to 200 characters, values at most 64 KB. */
+    readonly store: {
+        get(key: string): Json;
+        /** `options.ttl` is accepted and not yet applied. */
+        set(key: string, value: Json, options?: {
+            ttl?: number;
+        }): void;
+        /** Sets only if the stored value is still `ifEquals` (null: absent). Returns whether it did. */
+        set(key: string, value: Json, options: {
+            ifEquals: Json;
+            ttl?: number;
+        }): boolean;
+        /** Adds `by` (default 1) in one step and returns the new number. */
+        incr(key: string, by?: number): number;
+        delete(key: string): void;
+    };
+    /**
+     * Hashes and HMACs computed by the host. The key is the install secret you
+     * name; your code sees only the result. `{{secrets.x}}` in `message` is
+     * replaced with that secret. `alg` is sha256 or sha512, `encoding` hex
+     * (default) or base64.
+     */
+    readonly crypto: {
+        hmac(alg: 'sha256' | 'sha512', secretName: string, message: string, encoding?: 'hex' | 'base64'): string;
+        sha256(message: string, encoding?: 'hex' | 'base64'): string;
+        hash(alg: 'sha256' | 'sha512', message: string, encoding?: 'hex' | 'base64'): string;
+    };
+    /** Needs the `records.write` scope. */
+    readonly records: {
+        upsert(records: Json | Json[]): Json;
+    };
+    readonly log: Log;
+}
+export type ActionFn<I = any, O = any, Config = Record<string, any>> = (input: I, ctx: Ctx<Config>) => O | Promise<O>;
+export type Actions = Record<string, ActionFn>;

package/dist/types.js

@@ -0,0 +1,4 @@
+// Types for connector authors. They describe what the AirFone server accepts
+// (backend/crates/connectors/src/manifest.rs) and what it hands to JS actions
+// (js.rs, PRELUDE). Keep them in step with those files.
+export {};