@asturiu/v0-sdk 0.0.0-stage → 1.0.0

package/dist/definition-set.js

@@ -0,0 +1,659 @@
+/**
+ * Definition sets and Tenant keys (ADR-029, ADR-030) — the part a Tenant's own
+ * application server uses. A Tenant keeps its whole Definition set as one file;
+ * when its application starts, `applyDefinitions` sends it through the Tenant
+ * API, signed with a Tenant key whose private half never leaves the Tenant.
+ *
+ * Dependency-free and Web Crypto only, like the rest of the kit; the signing
+ * functions refuse to run in a browser, so a key bundled by mistake fails
+ * instead of working.
+ */
+import { SDK_USER_AGENT } from "./version.js";
+import { encodeSelector } from "./tags.js";
+/**
+ * Every Entry type of a set by its key, wherever it is declared. When a key is
+ * declared twice the first one wins here (shared, then Wallet types in order);
+ * the Engine refuses such a set.
+ */
+export function entryTypesOf(set) {
+    const out = {};
+    for (const [ek, e] of Object.entries(set.shared_entries ?? {}))
+        out[ek] = { ...e, wallet: null };
+    for (const [wk, w] of Object.entries(set.wallets ?? {}))
+        for (const [ek, e] of Object.entries(w.entries ?? {}))
+            if (!out[ek])
+                out[ek] = { ...e, wallet: wk };
+    return out;
+}
+/** The Entry type keys a Wallet type accepts: those it owns, then the shared ones it names in `accepts`. */
+export function acceptedBy(wallet) {
+    return [...new Set([...Object.keys(wallet.entries ?? {}), ...(wallet.accepts ?? [])])];
+}
+/**
+ * A set with Entry types at the top level, as the tree — the same rule as for
+ * fields: an Entry type accepted by exactly one Wallet type moves under it;
+ * one accepted by several Wallet types, or by none, goes to `shared_entries`
+ * and the Wallet types that accept it name it in `accepts`. The Definitions
+ * the set describes do not change.
+ */
+export function nestDefinitionSet(flat) {
+    const users = new Map();
+    for (const [wk, w] of Object.entries(flat.wallets ?? {}))
+        for (const ek of new Set(w.accepts ?? []))
+            users.set(ek, [...(users.get(ek) ?? []), wk]);
+    const owned = (ek) => (users.get(ek)?.length ?? 0) === 1 && Object.prototype.hasOwnProperty.call(flat.entries ?? {}, ek);
+    const shared_entries = {};
+    for (const [ek, e] of Object.entries(flat.entries ?? {}))
+        if (!owned(ek))
+            shared_entries[ek] = e;
+    const wallets = {};
+    for (const [wk, w] of Object.entries(flat.wallets ?? {})) {
+        const { accepts, ...rest } = w;
+        const keys = [...new Set(accepts ?? [])];
+        const own = Object.fromEntries(keys.filter(owned).map((ek) => [ek, flat.entries[ek]]));
+        const others = keys.filter((ek) => !owned(ek));
+        wallets[wk] = { ...rest, ...(Object.keys(own).length ? { entries: own } : {}), ...(others.length ? { accepts: others } : {}) };
+    }
+    return {
+        ...(flat.shared_fields ? { shared_fields: flat.shared_fields } : {}),
+        ...(Object.keys(shared_entries).length ? { shared_entries } : {}),
+        wallets,
+        ...(flat.acknowledge ? { acknowledge: flat.acknowledge } : {}),
+    };
+}
+/**
+ * JSON with object keys sorted and `undefined` dropped: the same bytes for the
+ * same value wherever it is computed, so the kit and the Engine agree on a hash.
+ */
+export function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value ?? null);
+    if (Array.isArray(value))
+        return `[${value.map((v) => (v === undefined ? "null" : canonicalJson(v))).join(",")}]`;
+    const obj = value;
+    const keys = Object.keys(obj).filter((k) => obj[k] !== undefined).sort();
+    return `{${keys.map((k) => `${JSON.stringify(k)}:${canonicalJson(obj[k])}`).join(",")}}`;
+}
+/** The set without `acknowledge`, canonical: what its hash covers. */
+export function definitionSetHashInput(set) {
+    const { acknowledge: _a, ...rest } = set;
+    return canonicalJson(rest);
+}
+/** SHA-256 hex of the set's canonical form, as the Engine reports it (`hash`). */
+export async function definitionSetHash(set) {
+    return hex(await subtle().digest("SHA-256", new TextEncoder().encode(definitionSetHashInput(set))));
+}
+// ----------------------------------------------------------- Tenant API
+/**
+ * The Tenant API's routes (ADR-030, decision 5; ADR-038; ADR-039; ADR-057;
+ * ADR-058; ADR-059): the only paths it forwards, and the scope each needs. A
+ * route whose scope is `null` is reached by any live key of the Tenant.
+ */
+export const TENANT_API_ROUTES = [
+    { method: "POST", path: "/tenant/v0/definitions", scope: "definitions" },
+    { method: "GET", path: "/tenant/v0/definitions/status", scope: "definitions" },
+    { method: "GET", path: "/tenant/v0/branding", scope: "branding" },
+    { method: "PUT", path: "/tenant/v0/branding", scope: "branding" },
+    { method: "GET", path: "/tenant/v0/portal", scope: "portal" },
+    { method: "PUT", path: "/tenant/v0/portal", scope: "portal" },
+    { method: "GET", path: "/tenant/v0/tiers", scope: "tiers" },
+    { method: "PUT", path: "/tenant/v0/tiers", scope: "tiers" },
+    { method: "PUT", path: "/tenant/v0/customers/:cst/entitlement", scope: "entitlements" },
+    { method: "GET", path: "/tenant/v0/customers/:cst/entitlements", scope: "entitlements" },
+    // A Tenant's agent reads its tier and use (ADR-064 §11). Paying stays with people.
+    { method: "GET", path: "/tenant/v0/subscription", scope: null },
+    // Tags (ADR-057 §7): the Tenant's own tags, and tagging its Customers, by name.
+    { method: "GET", path: "/tenant/v0/tags", scope: "tags" },
+    { method: "PUT", path: "/tenant/v0/tags/:name", scope: "tags" },
+    { method: "PUT", path: "/tenant/v0/customers/:cst/tags/:name", scope: "tags" },
+    { method: "DELETE", path: "/tenant/v0/customers/:cst/tags/:name", scope: "tags" },
+    // The Engine, its changesets and the Tenant's feedback (ADR-054 §7, ADR-059 §5): any live key, no scope.
+    { method: "GET", path: "/tenant/v0/engine", scope: null },
+    // The calling key's own record (ADR-074 §8): any live key, no scope.
+    { method: "GET", path: "/tenant/v0/key", scope: null },
+    { method: "GET", path: "/tenant/v0/changesets", scope: null },
+    { method: "PUT", path: "/tenant/v0/changesets/:n/status", scope: null },
+    { method: "POST", path: "/tenant/v0/feedback", scope: null },
+    { method: "GET", path: "/tenant/v0/feedback", scope: null },
+    { method: "POST", path: "/tenant/v0/feedback/:tkt/posts", scope: null },
+    // Tickets and announcements (ADR-058 §10): the Tenant's servers as a party of their own Tenant's tickets.
+    { method: "GET", path: "/tenant/v0/tickets", scope: "tickets" },
+    { method: "POST", path: "/tenant/v0/tickets", scope: "tickets" },
+    { method: "GET", path: "/tenant/v0/tickets/:tkt", scope: "tickets" },
+    { method: "PATCH", path: "/tenant/v0/tickets/:tkt", scope: "tickets" },
+    { method: "POST", path: "/tenant/v0/tickets/:tkt/posts", scope: "tickets" },
+    { method: "GET", path: "/tenant/v0/announcements", scope: "tickets" },
+    { method: "POST", path: "/tenant/v0/announcements", scope: "tickets" },
+    { method: "GET", path: "/tenant/v0/announcements/:tkt", scope: "tickets" },
+    { method: "PATCH", path: "/tenant/v0/announcements/:tkt", scope: "tickets" },
+    { method: "DELETE", path: "/tenant/v0/announcements/:tkt", scope: "tickets" },
+];
+export const TENANT_KEY_SCOPES = ["definitions", "branding", "portal", "tiers", "entitlements", "tags", "tickets"];
+/** What a Tenant keeps in its repository (ADR-038, decision 4): one key may carry any of these together. */
+export const REPOSITORY_SCOPES = ["definitions", "branding", "portal", "tiers"];
+/** Why a key cannot carry these scopes, or null: at least one known scope, none twice, and `entitlements` only on its own (the billing backend keeps its own key). */
+export function tenantKeyScopesProblem(scopes) {
+    if (!scopes.length)
+        return "a key needs at least one scope";
+    const unknown = scopes.filter((s) => !TENANT_KEY_SCOPES.includes(s));
+    if (unknown.length)
+        return `unknown scope: ${unknown.join(", ")}`;
+    if (new Set(scopes).size !== scopes.length)
+        return "a scope is named twice";
+    if (scopes.includes("entitlements") && scopes.length > 1)
+        return "entitlements is never combined with another scope: the billing backend keeps its own key";
+    return null;
+}
+/** A key's scopes from its stored or listed form: `scopes`, or `scope` as one scope or several separated by spaces (keys from before ADR-038). */
+export function tenantKeyScopesOf(record) {
+    const raw = Array.isArray(record.scopes) ? record.scopes : typeof record.scope === "string" ? record.scope.split(/\s+/) : [];
+    return raw.filter((s) => typeof s === "string" && TENANT_KEY_SCOPES.includes(s));
+}
+/** Whether a key with these scopes reaches a route: it carries the route's scope, or the route names none. */
+export function keyReachesRoute(scopes, route) {
+    return route.scope === null || scopes.includes(route.scope);
+}
+function matchPattern(pattern, path) {
+    const p = pattern.split("/");
+    const a = path.split("/");
+    if (p.length !== a.length)
+        return null;
+    const params = {};
+    for (let i = 0; i < p.length; i++) {
+        if (p[i].startsWith(":")) {
+            if (!a[i])
+                return null;
+            params[p[i].slice(1)] = decodeURIComponent(a[i]);
+        }
+        else if (p[i] !== a[i])
+            return null;
+    }
+    return params;
+}
+const fill = (pattern, params) => pattern.replace(/:([a-z_]+)/g, (_, k) => encodeURIComponent(params[k] ?? ""));
+/** The route a Tenant API request names, with its parameters, or null when the Tenant API has no such route. */
+export function matchTenantApiRoute(method, path) {
+    for (const route of TENANT_API_ROUTES) {
+        if (route.method !== method.toUpperCase())
+            continue;
+        const params = matchPattern(route.path, path);
+        if (params)
+            return { route, params };
+    }
+    return null;
+}
+/** A route pattern's parameters, or null when the path does not fit: shared with the Engine, which matches its forwards the same way. */
+export function matchRoutePattern(pattern, path) {
+    return matchPattern(pattern, path);
+}
+/** A route pattern with its parameters filled in, each encoded. */
+export function fillRoutePattern(pattern, params) {
+    return fill(pattern, params);
+}
+// ----------------------------------------------------------- Tenant keys
+export const TENANT_KEY_PREFIX = "atk";
+export const TENANT_ASSERTION_AUDIENCE = "asturiu-tenant-api";
+/** Longest an assertion may live, and the most a key may live (ADR-030). */
+export const TENANT_ASSERTION_MAX_SECONDS = 60;
+export const TENANT_KEY_MAX_DAYS = 180;
+/** `atk.<slug>.<key id>.<private key>` — the one environment variable a Tenant's server holds. */
+export function parseTenantKey(value) {
+    const m = /^atk\.([a-z0-9][a-z0-9-]*)\.([0-9a-f]{16})\.([A-Za-z0-9_-]{40,})$/.exec((value ?? "").trim());
+    if (!m)
+        throw new Error("not a Tenant key: expected atk.<slug>.<key id>.<private key>");
+    return { slug: m[1], kid: m[2], pkcs8: m[3] };
+}
+export function formatTenantKey(parts) {
+    return `${TENANT_KEY_PREFIX}.${parts.slug}.${parts.kid}.${parts.pkcs8}`;
+}
+/**
+ * A new Ed25519 key pair, made where this runs (the administrator's browser in
+ * the Admin UI): the private half as PKCS#8 for the Tenant to keep, the public
+ * half as the raw 32 bytes for Asturiu to store. Both base64url.
+ */
+export async function generateTenantKeyPair() {
+    const pair = (await subtle().generateKey({ name: "Ed25519" }, true, ["sign", "verify"]));
+    const [priv, pub] = await Promise.all([subtle().exportKey("pkcs8", pair.privateKey), subtle().exportKey("raw", pair.publicKey)]);
+    return { privatePkcs8: b64url(new Uint8Array(priv)), publicRaw: b64url(new Uint8Array(pub)) };
+}
+function refuseBrowser(what) {
+    const g = globalThis;
+    if (g.window !== undefined && g.document !== undefined)
+        throw new Error(`${what} runs on a server only: a Tenant key must never reach a browser`);
+}
+/**
+ * The signed assertion for one request (ADR-030, decision 3): valid for one
+ * minute, for this method, path and body, once. The key itself is never sent.
+ */
+export async function signTenantAssertion(opts) {
+    refuseBrowser("signTenantAssertion");
+    const k = parseTenantKey(opts.key);
+    const now = Math.floor((opts.now ?? Date.now()) / 1000);
+    const bytes = typeof opts.body === "string" ? new TextEncoder().encode(opts.body) : (opts.body ?? new Uint8Array());
+    const bdh = b64url(new Uint8Array(await subtle().digest("SHA-256", bytes)));
+    const header = { alg: "EdDSA", typ: "JWT", kid: k.kid };
+    const claims = { iss: k.slug, sub: k.kid, aud: TENANT_ASSERTION_AUDIENCE, htm: opts.method.toUpperCase(), htu: opts.path, bdh, iat: now, exp: now + TENANT_ASSERTION_MAX_SECONDS, jti: randomId() };
+    const input = `${b64urlText(JSON.stringify(header))}.${b64urlText(JSON.stringify(claims))}`;
+    const key = await subtle().importKey("pkcs8", fromB64url(k.pkcs8), { name: "Ed25519" }, false, ["sign"]);
+    const sig = await subtle().sign({ name: "Ed25519" }, key, new TextEncoder().encode(input));
+    return `${input}.${b64url(new Uint8Array(sig))}`;
+}
+const consoleLog = {
+    info: (m, d) => console.info(`[asturiu] ${m}`, d ?? ""),
+    warn: (m, d) => console.warn(`[asturiu] ${m}`, d ?? ""),
+    error: (m, d) => console.error(`[asturiu] ${m}`, d ?? ""),
+};
+/**
+ * What every Tenant API call throws when the Engine answers with an error
+ * (ADR-074 §2): `status` tells a route this Engine lacks (`404`) from a
+ * refusal (`401`, `403`, `409`, `422`). `type` and `detail` are the
+ * problem document's. A network failure is not one: `fetch` throws its own.
+ */
+export class TenantApiError extends Error {
+    status;
+    type;
+    detail;
+    /** The whole problem document, with `issues` when the Engine names them. */
+    problem;
+    constructor(status, problem) {
+        const p = problem && typeof problem === "object" ? problem : null;
+        const detail = typeof p?.detail === "string" ? p.detail : null;
+        const title = typeof p?.title === "string" ? p.title : null;
+        super(detail ?? title ?? `HTTP ${status}`);
+        this.name = "TenantApiError";
+        this.status = status;
+        this.type = typeof p?.type === "string" ? p.type : null;
+        this.detail = detail;
+        this.problem = p;
+    }
+}
+const fail = (r) => new TenantApiError(r.status, r.json);
+/** The assertion signs the path alone; a query rides beside it (`?since=`), as the Operations API checks the route's path. */
+async function tenantCall(opts) {
+    const text = opts.body === undefined ? "" : JSON.stringify(opts.body);
+    const assertion = await signTenantAssertion({ key: opts.key, method: opts.method, path: opts.path, body: text });
+    const f = opts.fetch ?? ((input, init) => globalThis.fetch(input, init));
+    // The SDK names its version, which the Engine records on the key as `last_sdk_version` (ADR-074 §4): how an administrator sees what a Tenant runs.
+    const headers = { authorization: `Asturiu-Assertion ${assertion}`, accept: "application/json", "user-agent": SDK_USER_AGENT };
+    if (text)
+        headers["content-type"] = "application/json";
+    if (opts.idempotencyKey)
+        headers["idempotency-key"] = opts.idempotencyKey;
+    const q = Object.entries(opts.query ?? {}).filter((e) => e[1] !== undefined && e[1] !== "");
+    const search = q.length ? `?${new URLSearchParams(q.map(([k, v]) => [k, String(v)])).toString()}` : "";
+    const res = await f(`${opts.baseUrl.replace(/\/+$/, "")}${opts.path}${search}`, { method: opts.method, headers, body: text || undefined });
+    const keyExpires = res.headers.get("asturiu-key-expires");
+    if (keyExpires)
+        (opts.log ?? consoleLog).warn("the Tenant key expires soon; create its successor in the Admin UI and replace the environment variable", { expires: keyExpires });
+    const json = await res.json().catch(() => null);
+    return { status: res.status, json, keyExpires };
+}
+/**
+ * Send the application's Definition set when it starts (ADR-029, the
+ * repository flow). Never throws and never blocks start-up: the outcome is
+ * logged — applied, unchanged, waiting for a tenant administrator, or refused
+ * with the reasons — and returned.
+ */
+export async function applyDefinitions(opts) {
+    const log = opts.log ?? consoleLog;
+    try {
+        refuseBrowser("applyDefinitions");
+        const set = typeof opts.set === "string" ? JSON.parse(opts.set) : opts.set;
+        const hash = await definitionSetHash(set);
+        // A fresh key per start: the submission is idempotent by its hash already, and a replayed answer would
+        // report "waiting" for a plan an administrator has since approved.
+        const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "POST", path: "/tenant/v0/definitions", body: set, idempotencyKey: `definitions-${hash.slice(0, 32)}-${randomId()}`, fetch: opts.fetch, log });
+        if (r.status >= 400 && r.json?.status !== "refused") {
+            const message = r.json?.detail ?? r.json?.title ?? `HTTP ${r.status}`;
+            log.error("Definition set not submitted", { status: r.status, message });
+            return { status: "error", message };
+        }
+        const out = r.json;
+        if (out.status === "applied")
+            log.info("Definition set applied", { revision: out.revision, hash: out.hash, changes: out.summary?.changes });
+        else if (out.status === "unchanged")
+            log.info("Definition set unchanged", { revision: out.revision });
+        else if (out.status === "waiting" && out.reverted_in)
+            log.warn(`Definition set waits for a tenant administrator: an administrator reverted it in revision ${out.reverted_in}; correct the repository's file, or have it approved again`, { plan: out.plan_id, approve: out.approve_url });
+        else if (out.status === "waiting")
+            log.warn("Definition set waits for a tenant administrator: it changes existing data", { plan: out.plan_id, approve: out.approve_url, unsafe: out.summary?.unsafe });
+        else
+            log.error("Definition set refused", { reasons: out.reasons });
+        return out;
+    }
+    catch (err) {
+        const message = err.message;
+        log.error("Definition set not submitted", { message });
+        return { status: "error", message };
+    }
+}
+async function applyWhole(what, opts) {
+    const log = opts.log ?? consoleLog;
+    const label = what === "branding" ? "Branding" : what === "portal" ? "Portal options" : "Tiers";
+    try {
+        refuseBrowser(what === "branding" ? "applyBranding" : what === "portal" ? "applyPortal" : "applyTiers");
+        const body = typeof opts.body === "string" ? JSON.parse(opts.body) : opts.body;
+        const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "PUT", path: `/tenant/v0/${what}`, body, idempotencyKey: `${what}-${randomId()}`, fetch: opts.fetch, log });
+        if (r.status >= 400) {
+            const message = r.json?.detail ?? r.json?.title ?? `HTTP ${r.status}`;
+            log.error(`${label} not applied`, { status: r.status, message, ...(r.json?.issues ? { issues: r.json.issues } : {}) });
+            return { status: "error", message, ...(r.json?.issues ? { problems: r.json.issues } : {}) };
+        }
+        const out = r.json;
+        log.info(out.status === "applied" ? `${label} applied` : `${label} unchanged`);
+        if (out.kept?.length)
+            log.warn("these portal pages stay where an administrator moved them (the Tenant's application); leave them out, or ask an administrator to bring them back", { pages: out.kept });
+        return out;
+    }
+    catch (err) {
+        const message = err.message;
+        log.error(`${label} not applied`, { message });
+        return { status: "error", message };
+    }
+}
+/**
+ * Send the branding the repository keeps when the application starts
+ * (ADR-038): the theme, `primary_color` and the images, inline
+ * (`inlineImage(bytes, type)`) — everything the Admin UI's Branding tab sets
+ * except addresses. The whole desired state of those keys: one left out is
+ * cleared, so send the whole theme. A string is read as JSON (a
+ * `branding.json` kept in the repository, as the Admin UI exports it).
+ * Applies at once; never throws, never blocks start-up.
+ */
+export async function applyBranding(opts) {
+    return applyWhole("branding", { ...opts, body: opts.branding });
+}
+/**
+ * Send the portal options the repository keeps when the application starts
+ * (ADR-038, ADR-039): the switches and which pages show. A switch left out is
+ * on, a page left out is in the portal; a page an administrator moved to the
+ * application keeps its redirect and comes back in `kept`. Like `applyBranding`.
+ */
+export async function applyPortal(opts) {
+    return applyWhole("portal", { ...opts, body: opts.portal });
+}
+/**
+ * Send the tiers the repository keeps when the application starts (ADR-061
+ * §10). Run it after `applyDefinitions`, as tiers name Wallet types by key.
+ * Like `applyBranding`, it never blocks start-up.
+ */
+export async function applyTiers(opts) {
+    return applyWhole("tiers", { ...opts, body: opts.tiers });
+}
+/** The tiers as stored, in the shape `applyTiers` takes. Like `readBranding`. */
+export async function readTiers(opts) {
+    refuseBrowser("readTiers");
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/tiers", fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** What one Customer may do now, for a server-side check or a background job (ADR-061 §9), with a key of scope `entitlements`. */
+export async function readEntitlements(opts) {
+    refuseBrowser("readEntitlements");
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: `/tenant/v0/customers/${encodeURIComponent(opts.customer)}/entitlements`, fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/**
+ * The branding as stored, in the shape `applyBranding` takes: to take the
+ * look designed in the Admin UI into the repository before the tab is handed
+ * over, or to compare. Readable whatever the tab's source. Throws on an error.
+ */
+export async function readBranding(opts) {
+    refuseBrowser("readBranding");
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/branding", fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** The portal options as stored, in the shape `applyPortal` takes. Like `readBranding`. */
+export async function readPortal(opts) {
+    refuseBrowser("readPortal");
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/portal", fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** Report a Customer's tier (ADR-023, ADR-061), signed with a key of scope `entitlements`. */
+export async function reportEntitlement(opts) {
+    refuseBrowser("reportEntitlement");
+    const path = `/tenant/v0/customers/${encodeURIComponent(opts.customer)}/entitlement`;
+    const body = { tier: opts.tier, status: opts.status ?? "active", ...(opts.period_end !== undefined ? { period_end: opts.period_end } : {}), ...(opts.members ? { members: opts.members } : {}) };
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "PUT", path, body, idempotencyKey: opts.idempotencyKey ?? `entitlement-${opts.customer}-${opts.tier}-${Date.now()}`, fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** The Tenant's own tier and use (ADR-064 §11), for its server or its agent. Read-only: paying stays with people. */
+export async function readTenantSubscription(opts) {
+    refuseBrowser("readTenantSubscription");
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/subscription", fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** The current revision and hash, and what waits for approval. */
+export async function definitionStatus(opts) {
+    refuseBrowser("definitionStatus");
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/definitions/status", fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** The Engine's version, its latest changeset, the Engine site's addresses and the SDK versions it serves. Any live key of the Tenant. */
+export async function readEngine(opts) {
+    refuseBrowser("readEngine");
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/engine", fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** Every changeset after `since`, each with this Tenant's ticket and status when it has one. */
+export async function readChangesets(opts) {
+    refuseBrowser("readChangesets");
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/changesets", query: { since: opts.since }, fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** Where this Tenant stands with a changeset: `in_progress` while applying it, `resolved` with the SDK version installed, `canceled` with the reason. A note becomes a post. */
+export async function setChangesetStatus(opts) {
+    refuseBrowser("setChangesetStatus");
+    const body = { status: opts.status, ...(opts.applied_version ? { applied_version: opts.applied_version } : {}), ...(opts.reason ? { reason: opts.reason } : {}), ...(opts.note ? { note: opts.note } : {}) };
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "PUT", path: `/tenant/v0/changesets/${opts.number}/status`, body, idempotencyKey: `changeset-${opts.number}-${await digest(JSON.stringify(body))}`, fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** Report what the Engine cannot do, or does otherwise than documented. The same report sent twice is one ticket: the key is the body's hash. */
+export async function sendFeedback(opts) {
+    refuseBrowser("sendFeedback");
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "POST", path: "/tenant/v0/feedback", body: opts.report, idempotencyKey: `feedback-${await digest(JSON.stringify(opts.report))}`, fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** The Tenant's feedback tickets that changed after the cursor, with the replies it may read; keep `next` for the next call. */
+export async function readFeedback(opts) {
+    refuseBrowser("readFeedback");
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/feedback", query: { since: opts.since }, fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** Answer on one of the Tenant's feedback tickets. */
+export async function replyToFeedback(opts) {
+    refuseBrowser("replyToFeedback");
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "POST", path: `/tenant/v0/feedback/${encodeURIComponent(opts.id)}/posts`, body: { body: opts.body }, idempotencyKey: `feedback-reply-${await digest(`${opts.id}|${opts.body}`)}`, fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** The calling key's own record: which Tenant it is for, what it reaches and when it expires. Any live key. */
+export async function readKey(opts) {
+    refuseBrowser("readKey");
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/key", fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** The Tenant's tags (ADR-057), with a key of scope `tags`. */
+export async function readTags(opts) {
+    refuseBrowser("readTags");
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/tags", fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json?.items ?? [];
+}
+/** Create the tag or change it, by name, so a server keeps its tags in step. `created` says which happened. */
+export async function setTag(opts) {
+    refuseBrowser("setTag");
+    const body = opts.change ?? {};
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "PUT", path: `/tenant/v0/tags/${encodeURIComponent(opts.name)}`, body, idempotencyKey: `tag-${await digest(`${opts.name}|${JSON.stringify(body)}`)}`, fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** Put a tag on one of the Tenant's Customers. `added` is false when the Customer had it already. */
+export async function tagCustomer(opts) {
+    refuseBrowser("tagCustomer");
+    const path = `/tenant/v0/customers/${encodeURIComponent(opts.customer)}/tags/${encodeURIComponent(opts.tag)}`;
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "PUT", path, idempotencyKey: `tag-on-${await digest(path)}-${randomId()}`, fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** Take a tag off one of the Tenant's Customers. `removed` is false when the Customer did not have it. */
+export async function untagCustomer(opts) {
+    refuseBrowser("untagCustomer");
+    const path = `/tenant/v0/customers/${encodeURIComponent(opts.customer)}/tags/${encodeURIComponent(opts.tag)}`;
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "DELETE", path, idempotencyKey: `tag-off-${await digest(path)}-${randomId()}`, fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** The tickets the Tenant's servers are a party of (ADR-058 §10), with a key of scope `tickets`. */
+export async function listTickets(opts) {
+    refuseBrowser("listTickets");
+    const f = opts.filter ?? {};
+    const query = { status: f.status, type: f.type, archived: f.archived ? "true" : undefined, unread: f.unread ? "true" : undefined, tags: f.tags ? encodeSelector(f.tags) : undefined, limit: f.limit };
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/tickets", query, fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json?.items ?? [];
+}
+/** One ticket with its posts. Reading it marks it read for the Tenant's servers. */
+export async function readTicket(opts) {
+    refuseBrowser("readTicket");
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: `/tenant/v0/tickets/${encodeURIComponent(opts.id)}`, fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+export async function openTicket(opts) {
+    refuseBrowser("openTicket");
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "POST", path: "/tenant/v0/tickets", body: opts.ticket, idempotencyKey: `ticket-${await digest(JSON.stringify(opts.ticket))}`, fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** A reply on a ticket. `visibility: "side"` keeps it to the Tenant's own side. */
+export async function postToTicket(opts) {
+    refuseBrowser("postToTicket");
+    const body = { body: opts.body, ...(opts.visibility ? { visibility: opts.visibility } : {}), ...(opts.refs ? { refs: opts.refs } : {}) };
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "POST", path: `/tenant/v0/tickets/${encodeURIComponent(opts.id)}/posts`, body, idempotencyKey: `ticket-post-${await digest(`${opts.id}|${JSON.stringify(body)}`)}`, fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+export async function updateTicket(opts) {
+    refuseBrowser("updateTicket");
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "PATCH", path: `/tenant/v0/tickets/${encodeURIComponent(opts.id)}`, body: opts.change, idempotencyKey: `ticket-change-${await digest(`${opts.id}|${JSON.stringify(opts.change)}`)}-${randomId()}`, fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** The Tenant's announcements to its Customers, with every status, and the platform's announcements to the Tenant, read only. */
+export async function listAnnouncements(opts) {
+    refuseBrowser("listAnnouncements");
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: "/tenant/v0/announcements", query: { lang: opts.lang }, fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return { items: r.json?.items ?? [], platform: r.json?.platform ?? [] };
+}
+export async function readAnnouncement(opts) {
+    refuseBrowser("readAnnouncement");
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "GET", path: `/tenant/v0/announcements/${encodeURIComponent(opts.id)}`, fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** Start an announcement to the Tenant's Customers, to everyone or to an audience of tags. It starts as a draft; `publishAnnouncement` sends it, or `announcement.publish_at` schedules it. */
+export async function draftAnnouncement(opts) {
+    refuseBrowser("draftAnnouncement");
+    const body = { ...opts.announcement, to: "customers" };
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "POST", path: "/tenant/v0/announcements", body, idempotencyKey: `announcement-${await digest(JSON.stringify(body))}`, fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** Publish a draft announcement now: its status becomes `published`. */
+export async function publishAnnouncement(opts) {
+    return updateAnnouncement({ ...opts, change: { status: "published" } });
+}
+export async function updateAnnouncement(opts) {
+    refuseBrowser("updateAnnouncement");
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "PATCH", path: `/tenant/v0/announcements/${encodeURIComponent(opts.id)}`, body: opts.change, idempotencyKey: `announcement-change-${await digest(`${opts.id}|${JSON.stringify(opts.change)}`)}-${randomId()}`, fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+    return r.json;
+}
+/** Take a published announcement down: its status becomes `withdrawn`. */
+export async function withdrawAnnouncement(opts) {
+    return updateAnnouncement({ ...opts, change: { status: "withdrawn" } });
+}
+/** Delete an announcement that is still a draft; a published one is withdrawn instead. */
+export async function deleteAnnouncementDraft(opts) {
+    refuseBrowser("deleteAnnouncementDraft");
+    const r = await tenantCall({ key: opts.key, baseUrl: opts.baseUrl, method: "DELETE", path: `/tenant/v0/announcements/${encodeURIComponent(opts.id)}`, idempotencyKey: `announcement-delete-${await digest(opts.id)}`, fetch: opts.fetch });
+    if (r.status >= 400)
+        throw fail(r);
+}
+async function digest(text) {
+    const h = await subtle().digest("SHA-256", new TextEncoder().encode(text));
+    return Array.from(new Uint8Array(h).slice(0, 16), (b) => b.toString(16).padStart(2, "0")).join("");
+}
+// ------------------------------------------------------------- helpers
+function subtle() {
+    const s = globalThis.crypto?.subtle;
+    if (!s)
+        throw new Error("Web Crypto is not available in this runtime");
+    return s;
+}
+function randomId() {
+    const b = new Uint8Array(16);
+    globalThis.crypto.getRandomValues(b);
+    return b64url(b);
+}
+function hex(buf) {
+    return [...new Uint8Array(buf)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+export function b64url(bytes) {
+    let s = "";
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function b64urlText(text) {
+    return b64url(new TextEncoder().encode(text));
+}
+export function fromB64url(value) {
+    const s = atob(value.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((value.length + 3) % 4));
+    const out = new Uint8Array(s.length);
+    for (let i = 0; i < s.length; i++)
+        out[i] = s.charCodeAt(i);
+    return out;
+}
+//# sourceMappingURL=definition-set.js.map