@picked/app-kit 0.0.0-stage → 0.0.117-next.2

package/dist/esm/server.js

@@ -0,0 +1,279 @@
+import { APP_ASSERTION_HEADER as e, PICKED_CONFIG_PATH as t, PICKED_KEYS_PATH as n, SIGNATURE_HEADER as r, createAppAssertion as i, remoteKeySet as a, signerFor as o, trimTrailing as s, verifyBody as c, verifyMcpRequest as l, verifySessionToken as u } from "@picked/app-protocol";
+import { AppInstallationLabelsDocument as d, AppInstallationTokenCreateDocument as f, LabelsDeleteDocument as p, LabelsSetDocument as m, createAdminApiClient as h } from "@picked/admin-api-client";
+export * from "@picked/app-protocol";
+//#region src/link.ts
+var g = /^app_[a-z0-9]+$/;
+function _(e) {
+	return g.test(e);
+}
+var v = /^[a-z0-9_-]{1,64}$/;
+function y(e) {
+	if (!_(e.appId)) throw TypeError(`${e.appId} is not an app ID`);
+	if (!v.test(e.namespace) || !v.test(e.key)) throw TypeError(`${e.namespace}.${e.key} is not a label namespace and key`);
+	let t = new URL(`/apps/${e.appId}/open`, new URL(e.dashboardOrigin).origin);
+	return t.searchParams.set("label", `${e.namespace}.${e.key}`), t.searchParams.set("value", e.value), t.toString();
+}
+//#endregion
+//#region src/client.ts
+var b = 6e4, x = class extends Error {
+	userErrors;
+	constructor(e) {
+		super(e.map((e) => `${e.field.join(".")}: ${e.message}`).join("; ")), this.name = "LabelWriteError", this.userErrors = e;
+	}
+}, S = {
+	TEXT: "text",
+	NUMBER: "number",
+	BOOLEAN: "boolean",
+	JSON: "json"
+}, C = {
+	text: "TEXT",
+	number: "NUMBER",
+	boolean: "BOOLEAN",
+	json: "JSON"
+};
+function w(e) {
+	return {
+		...e,
+		type: S[e.type]
+	};
+}
+function T(e) {
+	if (e.length !== 0) throw new x(e.map((e) => ({
+		field: e.field ?? [],
+		message: e.message,
+		code: e.code
+	})));
+}
+function E(t) {
+	let n = s(t.apiUrl, "/"), r = h({
+		apiUrl: n,
+		...t.fetch === void 0 ? {} : { fetch: t.fetch }
+	}), { installationId: a } = t, c = t.token === void 0 || t.tokenExpiresAt === void 0 ? void 0 : {
+		token: t.token,
+		expiresAt: Date.parse(t.tokenExpiresAt)
+	}, l = async () => {
+		if (c !== void 0 && c.expiresAt - b > Date.now()) return c.token;
+		let s = await i(await o(t.privateKey), {
+			installationId: a,
+			audience: n
+		}), { appInstallationTokenCreate: l } = await r.request(f, { input: {
+			installationId: a,
+			...t.sessionToken === void 0 ? {} : { sessionToken: t.sessionToken }
+		} }, { headers: { [e]: s } });
+		return c = {
+			token: l.token,
+			expiresAt: Date.parse(l.expiresAt)
+		}, l.token;
+	}, u = async (e, t, n = {}) => r.request(e, t, {
+		...n,
+		headers: {
+			...n.headers,
+			"x-api-key": await l()
+		}
+	}), g = {
+		ownerType: "APP_INSTALLATION",
+		ownerId: a
+	}, _ = {
+		async list() {
+			return ((await u(d, { id: a })).appInstallation?.labels ?? []).map(w);
+		},
+		async get(e, t) {
+			return (await _.list()).find((n) => n.namespace === e && n.key === t);
+		},
+		async set(e, t = {}) {
+			let { labelsSet: n } = await u(m, { input: {
+				...g,
+				labels: e.map((e) => ({
+					...e,
+					type: C[e.type]
+				})),
+				atomic: t.atomic ?? !1
+			} });
+			return T(n.userErrors), {
+				labels: n.labels.map(w),
+				skipped: n.skipped.map(w)
+			};
+		},
+		async delete(e) {
+			let { labelsDelete: t } = await u(p, { input: {
+				...g,
+				labels: [...e]
+			} });
+			return T(t.userErrors), t.deletedLabelIds;
+		}
+	};
+	return {
+		labels: _,
+		token: l,
+		request: u
+	};
+}
+function D(e, t) {
+	return E({
+		apiUrl: e.apiUrl,
+		installationId: e.installationId,
+		privateKey: t.privateKey,
+		...e.token === void 0 || e.tokenExpiresAt === void 0 ? {} : {
+			token: e.token,
+			tokenExpiresAt: e.tokenExpiresAt
+		},
+		...t.sessionToken == null ? {} : { sessionToken: t.sessionToken },
+		...t.fetch === void 0 ? {} : { fetch: t.fetch }
+	});
+}
+//#endregion
+//#region src/server.ts
+function O(e, t = 200) {
+	return new Response(JSON.stringify(e), {
+		status: t,
+		headers: { "content-type": "application/json" }
+	});
+}
+function k(e, t) {
+	let n = t.frameAncestors.length > 0 ? t.frameAncestors.join(" ") : "'none'";
+	return new Response(e, { headers: {
+		"content-type": "text/html; charset=utf-8",
+		"content-security-policy": `frame-ancestors ${n}`,
+		"referrer-policy": "strict-origin",
+		"x-content-type-options": "nosniff"
+	} });
+}
+function A(e, t) {
+	return typeof e == "object" && !!e && "type" in e && e.type === t;
+}
+function j(e) {
+	return A(e, "workflow_tool.call");
+}
+function M(e) {
+	return A(e, "installation.created");
+}
+function N(e) {
+	return A(e, "installation.upgraded");
+}
+function P(e) {
+	return A(e, "workspace.published");
+}
+function F(e) {
+	return A(e, "installation.deleted");
+}
+async function I(e, t) {
+	try {
+		return O({ output: await e(t) });
+	} catch (e) {
+		return O({ error: { message: e instanceof Error ? e.message : String(e) } }, 422);
+	}
+}
+function L(e, t, n, r) {
+	return r !== void 0 && t === r ? { kind: "mcp" } : e === "POST" ? n === "/lifecycle" ? { kind: "lifecycle" } : n === "/events" ? { kind: "event" } : n.startsWith("/tools/") ? {
+		kind: "tool",
+		name: n.slice(7)
+	} : null : null;
+}
+async function R(e, t, n) {
+	let r = n === "" ? null : JSON.parse(n);
+	if (t.kind === "lifecycle") return M(r) ? await e.onInstall?.(r) : N(r) ? await e.onUpgrade?.(r) : F(r) && await e.onUninstall?.(r), O({ ok: !0 });
+	if (t.kind === "event") return P(r) && await e.onEvent?.(r), O({ ok: !0 });
+	let i = t.kind === "tool" ? t.name : "", a = e.tools?.[i];
+	return a === void 0 || !j(r) ? O({ error: { message: `Unknown tool ${i}` } }, 404) : I(a, r);
+}
+function z(e) {
+	let t = s(e.basePath ?? "", "/");
+	return async (n) => {
+		let i = new URL(n.url).pathname, a = t !== "" && i.startsWith(t) ? i.slice(t.length) : i, o = L(n.method, i, a, e.mcp?.path);
+		if (o === null && e.manifest !== void 0 && a === "/manifest.json") return O(e.manifest);
+		if (o === null) return e.fallback === void 0 ? O({ error: "not_found" }, 404) : e.fallback(n);
+		let s = n.method === "GET" ? "" : await n.text();
+		if (o.kind !== "mcp" || e.mcp === void 0) return await c(e.pickedKeys, s, n.headers.get(r)) ? R(e, o, s) : O({ error: "invalid_signature" }, 401);
+		let u = await l(e.pickedKeys, n.headers, s);
+		return u === null ? O({ error: "invalid_signature" }, 401) : e.mcp.handle(new Request(n.url, {
+			method: n.method,
+			headers: n.headers,
+			...n.method === "GET" ? {} : { body: s }
+		}), u);
+	};
+}
+function B(e) {
+	let t = e.headers.get("authorization") ?? "";
+	return t.startsWith("Bearer ") && t.length > 7 ? t.slice(7) : null;
+}
+async function V(e, t) {
+	let n = B(e);
+	return n === null ? null : u(t, n);
+}
+function H(e, t) {
+	let n = e?.trim() ?? "";
+	if (n === "") throw Error(t);
+	return n;
+}
+var U = "picked-api";
+function W(e, t) {
+	if (typeof e != "object" || !e) return;
+	let n = Reflect.get(e, t);
+	return typeof n == "string" && n !== "" ? n : void 0;
+}
+function G(e, t) {
+	let n;
+	try {
+		n = JSON.parse(e.VERCEL_RELATED_PROJECTS ?? "[]");
+	} catch {
+		return;
+	}
+	if (!Array.isArray(n)) return;
+	let r = n.find((e) => W(Reflect.get(Object(e), "project"), "name") === t);
+	if (r === void 0) return;
+	let i = Reflect.get(Object(r), "preview"), a = Reflect.get(Object(r), "production"), o;
+	return e.VERCEL_ENV === "preview" ? o = W(i, "customEnvironment") ?? W(i, "branch") : e.VERCEL_ENV === "production" && (o = W(a, "alias") ?? W(a, "url")), o === void 0 ? void 0 : `https://${o}`;
+}
+function K(e) {
+	if (typeof e != "object" || !e) return;
+	let t = Reflect.get(e, "dashboardOrigins");
+	if (Array.isArray(t)) return t.filter((e) => typeof e == "string");
+}
+function q(e) {
+	let t = e.fetch ?? fetch, n = e.refreshAfterMs ?? 3e5, r = e.timeoutMs ?? 5e3, i = [], a, o, s = async () => {
+		let n = await t(e.url, { signal: AbortSignal.timeout(r) });
+		if (!n.ok) return;
+		let o = K(await n.json());
+		o !== void 0 && (i = o, a = Date.now());
+	};
+	return async () => (a !== void 0 && Date.now() - a < n || (o ??= s().finally(() => {
+		o = void 0;
+	}), await o.catch(() => void 0)), [...i]);
+}
+function J(e, r, i = {}) {
+	let o = H(e.PICKED_APP_PRIVATE_KEY, "Set PICKED_APP_PRIVATE_KEY to the app's private key, from `picked app keys generate`"), c = e.API_PORT === void 0 ? void 0 : `http://localhost:${e.API_PORT}`, l = s(H(e.PICKED_API_URL ?? G(e, U) ?? c, "Set PICKED_API_URL to the Picked API the app trusts"), "/"), u = (e.PICKED_DASHBOARD_ORIGINS ?? "").split(",").map((e) => e.trim()).filter((e) => e !== ""), d = e.DASHBOARD_PORT, f = u;
+	f.length === 0 && d !== void 0 && (f = [`http://localhost:${d}`, `http://127.0.0.1:${d}`]);
+	let p = e.VERCEL_ENV === "production" ? e.VERCEL_PROJECT_PRODUCTION_URL : e.VERCEL_BRANCH_URL, m = p === void 0 || p === "" ? void 0 : `https://${p}`, h = e.PICKED_APP_ID?.trim() ?? "", g = i.fetch === void 0 ? {} : { fetch: i.fetch };
+	return {
+		privateKey: o,
+		pickedUrl: l,
+		pickedKeys: a({
+			url: `${l}${n}`,
+			...g
+		}),
+		publicUrl: s(e.APP_PUBLIC_URL?.trim() || m || `http://localhost:${r}`, "/"),
+		frameAncestors: [...f],
+		dashboardOrigins: f.length > 0 ? () => Promise.resolve([...f]) : q({
+			url: `${l}${t}`,
+			...g,
+			...i.refreshAfterMs === void 0 ? {} : { refreshAfterMs: i.refreshAfterMs },
+			...i.timeoutMs === void 0 ? {} : { timeoutMs: i.timeoutMs }
+		}),
+		appId: _(h) ? h : null
+	};
+}
+function Y(e) {
+	return async (t) => {
+		let n = new URL(t.url), r = n.searchParams.get("__path");
+		if (r === null) return e(t);
+		n.searchParams.delete("__path"), n.pathname = r.startsWith("/") ? r : `/${r}`;
+		let i = t.method === "GET" || t.method === "HEAD" ? null : await t.text();
+		return e(new Request(n, {
+			method: t.method,
+			headers: t.headers,
+			body: i
+		}));
+	};
+}
+//#endregion
+export { x as LabelWriteError, z as createAppHandler, E as createInstallationClient, D as installationClientFor, y as installationLinkUrl, _ as isAppId, O as json, k as page, J as readAppEnvironment, V as readSession, q as remoteDashboardOrigins, B as sessionTokenOf, Y as withRewrittenPath };

package/dist/esm/testing.js

@@ -0,0 +1,197 @@
+import { APP_ASSERTION_HEADER as e, PICKED_KEYS_PATH as t, SIGNATURE_HEADER as n, createSessionToken as r, createSigner as i, generateKeyPair as a, signBody as o, signMcpRequest as s, staticKeySet as c, toJwks as l, verifyAppAssertion as u, verifySessionToken as d } from "@picked/app-protocol";
+//#region src/testing.ts
+var f = /^[a-z0-9_-]{1,64}$/;
+function p(e) {
+	return typeof e == "object" && !!e && !Array.isArray(e);
+}
+function m(e) {
+	return e === "TEXT" ? "text" : e === "NUMBER" ? "number" : e === "BOOLEAN" ? "boolean" : e === "JSON" ? "json" : null;
+}
+function h(e) {
+	if (!p(e)) return null;
+	let { namespace: t, key: n, value: r, increment: i, expiresIn: a, onlyIfAbsent: o, secret: s } = e, c = m(e.type);
+	return typeof t != "string" || typeof n != "string" || c === null ? null : {
+		namespace: t,
+		key: n,
+		type: c,
+		...typeof r == "string" ? { value: r } : {},
+		...typeof i == "number" ? { increment: i } : {},
+		...typeof a == "number" ? { expiresIn: a } : {},
+		...o === !0 ? { onlyIfAbsent: o } : {},
+		...s === !0 ? { secret: s } : {}
+	};
+}
+function g(e, t) {
+	let n = `${t.namespace}.${t.key}`, r = e.get(n);
+	if (t.onlyIfAbsent === !0 && r !== void 0) return {
+		label: r,
+		skipped: r.value !== t.value
+	};
+	let i = t.increment === void 0 ? t.value ?? "" : String(Number(r?.value ?? "0") + t.increment), a = {
+		namespace: t.namespace,
+		key: t.key,
+		type: t.type,
+		value: i,
+		secret: t.secret === !0,
+		expiresAt: t.expiresIn === void 0 ? null : new Date(Date.now() + t.expiresIn * 1e3).toISOString(),
+		updatedAt: (/* @__PURE__ */ new Date()).toISOString()
+	};
+	return e.set(n, a), {
+		label: a,
+		skipped: !1
+	};
+}
+function _(e) {
+	return {
+		...e,
+		type: e.type.toUpperCase()
+	};
+}
+function v(e, t) {
+	return Response.json({
+		data: null,
+		errors: [{
+			message: e,
+			extensions: { code: t }
+		}]
+	});
+}
+function y(e, t, n) {
+	let r = Array.isArray(n.labels) ? n.labels : [];
+	if (t === "AppInstallationLabelsDelete") {
+		let t = r.flatMap((e) => p(e) ? [`${String(e.namespace)}.${String(e.key)}`] : []).filter((t) => e.delete(t));
+		return Response.json({ data: { labelsDelete: {
+			deletedLabelIds: t,
+			userErrors: []
+		} } });
+	}
+	let i = r.map(h), a = i.findIndex((e) => e === null || !f.test(e.namespace) || !f.test(e.key));
+	if (a !== -1) {
+		let e = [{
+			field: [
+				"labels",
+				String(a),
+				"key"
+			],
+			message: "Key is invalid.",
+			code: "KEY_INVALID"
+		}];
+		return Response.json({ data: { labelsSet: {
+			labels: [],
+			skipped: [],
+			userErrors: e
+		} } });
+	}
+	let o = i.flatMap((t) => t === null ? [] : [g(e, t)]);
+	return Response.json({ data: { labelsSet: {
+		labels: o.filter((e) => !e.skipped).map((e) => _(e.label)),
+		skipped: o.filter((e) => e.skipped).map((e) => _(e.label)),
+		userErrors: []
+	} } });
+}
+async function b(f) {
+	let m = f.apiUrl ?? "https://api.picked.test", h = c([await i(f.appPrivateKey)]), g = await i((await a()).privateKey), b = /* @__PURE__ */ new Map(), x = /* @__PURE__ */ new Map(), S = [], C = (e) => {
+		let t = `appt_fake_${String(x.size + 1)}`;
+		return x.set(t, e), Promise.resolve({
+			token: t,
+			expiresAt: new Date(Date.now() + 36e5).toISOString()
+		});
+	}, w = async (t, n) => {
+		let r = t.get(e) ?? "", i = await u(h, r, { audience: m });
+		if (i === null || i.installationId !== n.installationId) return v("The app assertion does not verify", "UNAUTHENTICATED");
+		let a = typeof n.sessionToken == "string" ? await d(c([g]), n.sessionToken) : null;
+		return f.offlineAccess !== !0 && a?.installationId !== i.installationId ? v("The installation has no offline access; use the token Picked sends with each request", "FORBIDDEN") : Response.json({ data: { appInstallationTokenCreate: await C(i.installationId) } });
+	}, T = async (e, t) => {
+		let n = JSON.parse(t), r = p(n) && typeof n.operationName == "string" ? n.operationName : "", i = p(n) && p(n.variables) ? n.variables : {};
+		S.push({
+			operationName: r,
+			variables: i
+		});
+		let a = p(i.input) ? i.input : {};
+		if (r === "AppInstallationTokenCreate") return w(e, a);
+		let o = x.get(e.get("x-api-key") ?? "");
+		if (o === void 0) return v("Authentication failed: Invalid API key", "UNAUTHENTICATED");
+		let s = b.get(o) ?? /* @__PURE__ */ new Map();
+		if (b.set(o, s), r === "AppInstallationLabels") {
+			let e = i.id === o;
+			return Response.json({ data: { appInstallation: e ? { labels: [...s.values()].map(_) } : null } });
+		}
+		return a.ownerType !== "APP_INSTALLATION" || a.ownerId !== o ? v("Forbidden", "FORBIDDEN") : y(s, r, a);
+	};
+	return {
+		apiUrl: m,
+		fetch: async (e, n) => {
+			let r = new URL(e instanceof Request ? e.url : e);
+			return r.pathname === t ? Response.json(l([g])) : r.pathname === "/api/graphql" ? T(new Headers(n?.headers), typeof n?.body == "string" ? n.body : "{}") : Response.json({ error: { message: "Not found" } }, { status: 404 });
+		},
+		pickedKeys: c([g]),
+		labels: b,
+		received: S,
+		tokenFor: C,
+		async installationRef(e, t = {}) {
+			let { token: n, expiresAt: r } = await C(e);
+			return {
+				installationId: e,
+				organizationId: "org",
+				projectId: "proj_1",
+				apiUrl: m,
+				...t,
+				token: n,
+				tokenExpiresAt: r
+			};
+		},
+		async signedRequest(e, t) {
+			let r = JSON.stringify(t);
+			return new Request(e, {
+				method: "POST",
+				body: r,
+				headers: { [n]: await o(g, r) }
+			});
+		},
+		async mcpRequest(e, t, n) {
+			let r = JSON.stringify(n);
+			return new Request(e, {
+				method: "POST",
+				body: r,
+				headers: {
+					"content-type": "application/json",
+					...await s(g, t, r)
+				}
+			});
+		},
+		async sessionRequest(e) {
+			let t = await r(g, {
+				...e.ref,
+				userId: "user-test",
+				exp: Math.floor(Date.now() / 1e3) + 60
+			});
+			return new Request(e.url, {
+				method: e.method ?? "GET",
+				headers: {
+					authorization: `Bearer ${t}`,
+					"content-type": "application/json"
+				},
+				...e.body === void 0 ? {} : { body: JSON.stringify(e.body) }
+			});
+		}
+	};
+}
+function x(e, t, n, r = !1) {
+	return {
+		type: "workflow_tool.call",
+		...e,
+		tool: t,
+		arguments: n,
+		idempotencyKey: `wrun_test:${t}`,
+		run: {
+			runId: r ? "test_wrun" : "wrun_test",
+			nodeId: "n1",
+			test: r
+		}
+	};
+}
+function S(e) {
+	return (e.headers.get("set-cookie") ?? "").split(";")[0] ?? "";
+}
+//#endregion
+export { b as createFakePicked, S as oauthCookie, x as toolCall };

package/dist/types/client.d.ts

@@ -0,0 +1,145 @@
+import type { AdminApiRequestOptions, TadaDocumentNode } from '@picked/admin-api-client';
+import { type InstallationRef } from '@picked/app-protocol';
+/** How to read a label's `value`. */
+export type AppLabelType = 'text' | 'number' | 'boolean' | 'json';
+/** A label the app keeps for an installation, as Picked's `Label` type describes it. */
+export interface AppLabel {
+    namespace: string;
+    key: string;
+    type: AppLabelType;
+    /** The value, as a string to read through `type`; a secret label's value included. */
+    value: string;
+    /** Whether the value is kept in Vault. */
+    secret: boolean;
+    /** When the label expires, or null. */
+    expiresAt: string | null;
+    updatedAt: string;
+}
+/**
+ * A label to set, as Picked's `LabelInput` takes it. A namespace and a key are each 1-64
+ * lowercase letters, digits, underscores or hyphens; a value holds at most 64 KiB, and an
+ * installation holds at most 100 labels.
+ */
+export interface AppLabelInput {
+    namespace: string;
+    key: string;
+    type: AppLabelType;
+    /** The value, as a string that parses as `type`. */
+    value?: string;
+    /** What to add to a `number` label, in place of `value`. */
+    increment?: number;
+    /** Seconds until the label expires, from 1 to 31536000. */
+    expiresIn?: number;
+    /** Writes only when no live label has this namespace and key. */
+    onlyIfAbsent?: boolean;
+    /** Keeps the value in Vault: a `text` or `json` value, with no `increment` or `onlyIfAbsent`. */
+    secret?: boolean;
+}
+/** A label to remove, as Picked's `LabelIdentifierInput` takes it. */
+export interface AppLabelIdentifier {
+    namespace: string;
+    key: string;
+    /** Removes the label only while it holds this value. */
+    ifValue?: string;
+}
+/** A refused label write, as Picked's `LabelUserError` describes it. */
+export interface AppLabelUserError {
+    field: string[];
+    message: string;
+    code: string;
+}
+/** A label write Picked refused, carrying its user errors. */
+export declare class LabelWriteError extends Error {
+    readonly userErrors: readonly AppLabelUserError[];
+    /**
+     * Builds the error from Picked's user errors.
+     *
+     * @param {readonly AppLabelUserError[]} userErrors - Why Picked refused the write.
+     * @example new LabelWriteError([{ field: ['labels', '0', 'key'], message: 'Key is invalid.', code: 'KEY_INVALID' }])
+     */
+    constructor(userErrors: readonly AppLabelUserError[]);
+}
+/** The labels an app keeps for one installation in Picked, which the installation owns. */
+export interface InstallationLabels {
+    /** Every live label, secret values included. */
+    list: () => Promise<AppLabel[]>;
+    /** One live label, or undefined when none has the namespace and key. */
+    get: (namespace: string, key: string) => Promise<AppLabel | undefined>;
+    /**
+     * Creates or replaces labels, as `labelsSet` does, throwing {@link LabelWriteError} when
+     * Picked refuses one. `skipped` holds the live labels an `onlyIfAbsent` label left in place.
+     */
+    set: (labels: readonly AppLabelInput[], options?: {
+        atomic?: boolean;
+    }) => Promise<{
+        labels: AppLabel[];
+        skipped: AppLabel[];
+    }>;
+    /** Removes labels, as `labelsDelete` does, returning the ids removed. */
+    delete: (labels: readonly AppLabelIdentifier[]) => Promise<string[]>;
+}
+/** Calls Picked as one installation. */
+export interface InstallationClient {
+    /** The installation's labels. */
+    labels: InstallationLabels;
+    /**
+     * A short-lived token carrying the installation's scopes: the one Picked sent with the
+     * request being answered, or one minted with an app assertion, which Picked grants an app with
+     * offline access, or one answering a dashboard user's session. Renewed before it expires.
+     */
+    token: () => Promise<string>;
+    /**
+     * Runs a typed document with the installation's token and returns its `data`. Build the
+     * document with `graphql` from `@picked/admin-api-client`.
+     *
+     * @throws {Error} An `AdminApiResponseError` when Picked answers with GraphQL errors, and a
+     *   plain `Error` on a network failure, a timeout, or a response without GraphQL errors.
+     */
+    request: <Result, Variables extends Record<string, unknown>>(document: TadaDocumentNode<Result, Variables>, variables: Variables, options?: AdminApiRequestOptions) => Promise<Result>;
+}
+/** Where and as whom an installation client calls Picked. */
+export interface InstallationClientOptions {
+    /** The Picked API origin, as the request from Picked names it in `apiUrl`. */
+    apiUrl: string;
+    /** The installation. */
+    installationId: string;
+    /** The app's Ed25519 private key, as the base64 of its PKCS#8 DER or a PKCS#8 PEM. */
+    privateKey: string;
+    /** A token Picked sent with the request being answered, used until it nears expiry. */
+    token?: string;
+    /** When `token` expires. */
+    tokenExpiresAt?: string;
+    /**
+     * The session token of the dashboard user a page request comes from, which lets an app
+     * without offline access mint a token while it answers that user.
+     */
+    sessionToken?: string;
+    /** The fetch to send with; the global one by default. */
+    fetch?: typeof fetch;
+}
+/**
+ * Builds a client that calls Picked as one installation.
+ *
+ * @param {InstallationClientOptions} options - Where and as whom.
+ * @returns {InstallationClient} The client.
+ * @example createInstallationClient({ ...event, privateKey })
+ */
+export declare function createInstallationClient(options: InstallationClientOptions): InstallationClient;
+/**
+ * Builds the client for the installation a request names: with the token Picked sent, and for a
+ * page request, the session token the frame forwarded.
+ *
+ * @param {Pick<InstallationRef, 'apiUrl' | 'installationId' | 'token' | 'tokenExpiresAt'>} ref - The installation, as the request names it.
+ * @param {object} options - As whom and how.
+ * @param {string} options.privateKey - The app's private key.
+ * @param {string | null} [options.sessionToken] - The session token of a page request.
+ * @param {typeof fetch} [options.fetch] - The fetch to send with.
+ * @returns {InstallationClient} The client.
+ * @example installationClientFor(event, { privateKey: environment.privateKey })
+ */
+export declare function installationClientFor(ref: Pick<InstallationRef, 'apiUrl' | 'installationId' | 'token' | 'tokenExpiresAt'>, options: {
+    privateKey: string;
+    sessionToken?: string | null;
+    fetch?: typeof fetch;
+}): InstallationClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/types/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"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"}