@asturiu/v0-sdk 0.0.0-stage → 1.0.0

package/dist/definition-set.d.ts

@@ -0,0 +1,731 @@
+/**
+ * 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 type { TenantSubscriptionView } from "./tenant-subscription.js";
+import type { FieldValueType } from "./types.js";
+import type { CustomerEntitlements, TenantTierSet, TierRules } from "./tiers.js";
+import type { RevealLevel } from "./reveal.js";
+import type { FillMode, LocatorRule } from "./fill.js";
+import type { RepositoryBranding, RepositoryPortal, TenantSource } from "./branding.js";
+import type { PortalPage, PortalSwitch } from "./portal-options.js";
+import type { ChangesetStatus, FeedbackReport, TenantChangeset } from "./changesets.js";
+import type { AnnouncementItem, AnyStatus, Priority, TicketSummary, TicketView } from "./tickets.js";
+import { type TagColour, type TagEffect, type TagRule, type TagSelector, type TagView, type TagVisibility } from "./tags.js";
+/** A field's rules in a Definition set: a FieldDefinition without its `name`, which is the key it stands under. */
+export interface SetFieldSpec {
+    label?: string;
+    description?: string;
+    value_type: FieldValueType;
+    validation?: {
+        pattern?: string;
+        min?: number;
+        max?: number;
+        min_length?: number;
+        max_length?: number;
+        enum?: (string | number | boolean)[];
+    };
+    secret?: boolean;
+    reveal?: RevealLevel;
+    searchable?: boolean;
+    immutable?: boolean;
+    locked?: boolean;
+    /** ADR-046: the modes a Field may use, the first preselected. Absent: `value`, `internal`, `external`. */
+    filled_by?: FillMode[];
+    /** Resource type tokens an internal reference may point at (`fld`, `ent`, `wlt`, `att`, …). Absent: any. */
+    targets?: string[];
+    /**
+     * Definitions of this set a target must be of. A bare key is an Entry type, as in `accepts`; a Wallet type or a
+     * field is named by its address (`wallet:<key>`, `field:<entry>.<key>`, `field:shared.<key>`). Each restricts
+     * targets of its own kind. Absent: any.
+     */
+    target_definitions?: string[];
+    locator?: LocatorRule;
+}
+/** What belongs to the reference, wherever the field is declared. `fill_in` only with `required`. */
+export interface SetFieldReference {
+    required?: boolean;
+    order?: number;
+    fill_in?: unknown;
+}
+/** A field owned by its Entry type (address `<entry>.<key>`), or one of the shared fields (`{ use: "<key>" }`, optionally narrowing its modes here). */
+export type SetEntryField = (SetFieldSpec & SetFieldReference) | ({
+    use: string;
+    filled_by?: FillMode[];
+} & SetFieldReference);
+export interface SetEntry {
+    label?: string;
+    description?: string;
+    kind?: "file" | "folder";
+    nestable?: boolean;
+    /** Folders only: Entry type keys. */
+    contains?: string[];
+    customizable?: boolean;
+    value_types?: FieldValueType[];
+    secret_reveal_min?: RevealLevel;
+    /** The modes a custom field on this type may allow (ADR-046). Absent: all three. */
+    custom_filled_by?: FillMode[];
+    fields: Record<string, SetEntryField>;
+}
+export interface SetWallet {
+    label?: string;
+    description?: string;
+    /**
+     * The Entry types this Wallet type owns, by key; it accepts each of them and
+     * no other Wallet type may. An Entry type key is unique across the set.
+     */
+    entries?: Record<string, SetEntry>;
+    /** Entry types from `shared_entries` this Wallet type accepts, by key. */
+    accepts?: string[];
+    nestable?: boolean;
+    immutable?: boolean;
+    metering?: "storage" | "events";
+    event_retention_days?: number;
+    default_policy?: Record<string, unknown>;
+}
+/**
+ * Every Definition of one Tenant, as one document (ADR-029, ADR-031): Wallet
+ * types with the Entry types they own, Entry types with the fields they own,
+ * and what is shared on purpose — fields used by several Entry types
+ * (`shared_fields`, through `use`) and Entry types accepted by several Wallet
+ * types or by none (`shared_entries`, through `accepts`). Keys are permanent;
+ * labels are what people see. The tree is only how the set is written: an
+ * Entry type is one EntryDefinition, addressed `entry:<key>` wherever it is
+ * declared.
+ */
+export interface DefinitionSet {
+    shared_fields?: Record<string, SetFieldSpec>;
+    shared_entries?: Record<string, SetEntry>;
+    wallets: Record<string, SetWallet>;
+    /** `expose:<address>` for each change that makes values more visible. Not part of the set's hash. */
+    acknowledge?: string[];
+}
+/** One Entry type of a set with the Wallet type that owns it, or `null` for a shared one. */
+export interface SetEntryOf extends SetEntry {
+    wallet: string | null;
+}
+/**
+ * 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 declare function entryTypesOf(set: Pick<DefinitionSet, "wallets" | "shared_entries">): Record<string, SetEntryOf>;
+/** The Entry type keys a Wallet type accepts: those it owns, then the shared ones it names in `accepts`. */
+export declare function acceptedBy(wallet: SetWallet): string[];
+/** A set in the format of changeset 003: Entry types at the top level, Wallet types naming them in `accepts`. */
+export interface FlatDefinitionSet {
+    shared_fields?: Record<string, SetFieldSpec>;
+    entries: Record<string, SetEntry>;
+    wallets: Record<string, Omit<SetWallet, "entries" | "accepts"> & {
+        accepts: string[];
+    }>;
+    acknowledge?: string[];
+}
+/**
+ * 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 declare function nestDefinitionSet(flat: FlatDefinitionSet): DefinitionSet;
+/** The effect of one change, as a plan reports it (ADR-029, decision 5). */
+export type PlanEffect = "repins" | "creates" | "tightens" | "stays_pinned" | "may_stay_pinned" | "retires_values" | "withdraws" | "exposes";
+export interface PlanChange {
+    /** `wallet:<key>`, `entry:<key>`, `field:<entry>.<key>` or `field:shared.<key>`. */
+    address: string;
+    kind: "wallet" | "entry" | "field";
+    /** What changed, in a word: `registered`, `label`, `value_type`, `validation_tighter`, `field_added_required`, … */
+    change: string;
+    effect: PlanEffect;
+    safe: boolean;
+    /** Resources on this Definition per version, counted from their pins — never from their content. */
+    in_use?: {
+        version: number;
+        count: number;
+    }[];
+    detail?: Record<string, unknown>;
+}
+export interface PlanRefusal {
+    address?: string;
+    reason: string;
+}
+export interface DefinitionPlan {
+    plan_id: string;
+    based_on: number;
+    hash: string;
+    changes: PlanChange[];
+    refused: PlanRefusal[];
+    /** What the set still says in an older form, read as its current form (e.g. a reference value type, ADR-046). Nothing to approve. */
+    warnings?: PlanRefusal[];
+    /** Every change is safe: a submission may apply it at once under `auto_apply: safe`. */
+    safe: boolean;
+    /** Nothing would be published. */
+    empty: boolean;
+    expires_at: string;
+    /** The revision a revert plan brings back (ADR-049). */
+    reverts?: number;
+}
+export type DefinitionSubmitStatus = "unchanged" | "applied" | "waiting" | "refused";
+export interface DefinitionSubmitResult {
+    status: DefinitionSubmitStatus;
+    hash: string;
+    /** The revision now live: the new one when `applied`, the current one otherwise. */
+    revision: number;
+    plan_id?: string;
+    summary?: {
+        changes: number;
+        unsafe: number;
+    };
+    changes?: PlanChange[];
+    reasons?: PlanRefusal[];
+    /** What the set still says in an older form, read as its current form (ADR-046). */
+    warnings?: PlanRefusal[];
+    /** Where a tenant administrator approves a waiting plan. */
+    approve_url?: string;
+    /** The set waits because an administrator reverted it, in this revision (ADR-049). */
+    reverted_in?: number;
+}
+export interface DefinitionStatus {
+    revision: number;
+    hash: string | null;
+    source: "admin_ui" | "repository";
+    auto_apply: "safe" | "none";
+    waiting: {
+        plan_id: string;
+        hash: string;
+        created_at: string;
+    }[];
+}
+/**
+ * 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 declare function canonicalJson(value: unknown): string;
+/** The set without `acknowledge`, canonical: what its hash covers. */
+export declare function definitionSetHashInput(set: DefinitionSet | Record<string, unknown>): string;
+/** SHA-256 hex of the set's canonical form, as the Engine reports it (`hash`). */
+export declare function definitionSetHash(set: DefinitionSet | Record<string, unknown>): Promise<string>;
+/**
+ * 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 declare const TENANT_API_ROUTES: readonly {
+    method: string;
+    path: string;
+    scope: TenantKeyScope | null;
+}[];
+export type TenantKeyScope = "definitions" | "branding" | "portal" | "tiers" | "entitlements" | "tags" | "tickets";
+export declare const TENANT_KEY_SCOPES: readonly TenantKeyScope[];
+/** What a Tenant keeps in its repository (ADR-038, decision 4): one key may carry any of these together. */
+export declare const REPOSITORY_SCOPES: readonly TenantKeyScope[];
+/** 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 declare function tenantKeyScopesProblem(scopes: readonly string[]): string | 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 declare function tenantKeyScopesOf(record: {
+    scopes?: unknown;
+    scope?: unknown;
+}): TenantKeyScope[];
+export type TenantApiRoute = (typeof TENANT_API_ROUTES)[number];
+/** Whether a key with these scopes reaches a route: it carries the route's scope, or the route names none. */
+export declare function keyReachesRoute(scopes: readonly string[], route: Pick<TenantApiRoute, "scope">): boolean;
+/** The route a Tenant API request names, with its parameters, or null when the Tenant API has no such route. */
+export declare function matchTenantApiRoute(method: string, path: string): {
+    route: TenantApiRoute;
+    params: Record<string, string>;
+} | 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 declare function matchRoutePattern(pattern: string, path: string): Record<string, string> | null;
+/** A route pattern with its parameters filled in, each encoded. */
+export declare function fillRoutePattern(pattern: string, params: Record<string, string>): string;
+export declare const TENANT_KEY_PREFIX = "atk";
+export declare const TENANT_ASSERTION_AUDIENCE = "asturiu-tenant-api";
+/** Longest an assertion may live, and the most a key may live (ADR-030). */
+export declare const TENANT_ASSERTION_MAX_SECONDS = 60;
+export declare const TENANT_KEY_MAX_DAYS = 180;
+export interface TenantKeyParts {
+    slug: string;
+    kid: string;
+    /** PKCS#8 private key, base64url. */
+    pkcs8: string;
+}
+/** `atk.<slug>.<key id>.<private key>` — the one environment variable a Tenant's server holds. */
+export declare function parseTenantKey(value: string): TenantKeyParts;
+export declare function formatTenantKey(parts: TenantKeyParts): string;
+/**
+ * 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 declare function generateTenantKeyPair(): Promise<{
+    privatePkcs8: string;
+    publicRaw: string;
+}>;
+/**
+ * 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 declare function signTenantAssertion(opts: {
+    key: string;
+    method: string;
+    path: string;
+    body?: string | Uint8Array;
+    now?: number;
+}): Promise<string>;
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+type Logger = {
+    info: (msg: string, detail?: Record<string, unknown>) => void;
+    warn: (msg: string, detail?: Record<string, unknown>) => void;
+    error: (msg: string, detail?: Record<string, unknown>) => void;
+};
+/**
+ * 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 declare class TenantApiError extends Error {
+    readonly status: number;
+    readonly type: string | null;
+    readonly detail: string | null;
+    /** The whole problem document, with `issues` when the Engine names them. */
+    readonly problem: Record<string, unknown> | null;
+    constructor(status: number, problem: unknown);
+}
+/**
+ * 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 declare function applyDefinitions(opts: {
+    set: DefinitionSet | string;
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+    log?: Logger;
+}): Promise<DefinitionSubmitResult | {
+    status: "error";
+    message: string;
+}>;
+/** What `PUT /tenant/v0/branding` and `PUT /tenant/v0/portal` answer (ADR-038). `kept`, on the portal's answer: redirected pages the body named, left as an administrator set them (ADR-039). */
+export interface TenantRepositoryResult {
+    status: "unchanged" | "applied";
+    kept?: PortalPage[];
+}
+/**
+ * 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 declare function applyBranding(opts: {
+    branding: RepositoryBranding | string;
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+    log?: Logger;
+}): Promise<TenantRepositoryResult | {
+    status: "error";
+    message: string;
+    problems?: unknown;
+}>;
+/**
+ * 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 declare function applyPortal(opts: {
+    portal: RepositoryPortal | string;
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+    log?: Logger;
+}): Promise<TenantRepositoryResult | {
+    status: "error";
+    message: string;
+    problems?: unknown;
+}>;
+/** The block a repository keeps (ADR-061 §10): the tiers, `default_tier` and `tier_rules`. */
+export type RepositoryTiers = Pick<TenantTierSet, "tiers" | "default_tier"> & {
+    tier_rules?: Partial<Omit<TierRules, "changed_at">>;
+};
+/**
+ * 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 declare function applyTiers(opts: {
+    tiers: RepositoryTiers | string;
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+    log?: Logger;
+}): Promise<TenantRepositoryResult | {
+    status: "error";
+    message: string;
+    problems?: unknown;
+}>;
+/** What `GET /tenant/v0/tiers` answers: who edits the tab, and the block a `PUT` would send back unchanged. */
+export interface RepositoryTiersState extends RepositoryTiers {
+    source: TenantSource;
+}
+/** The tiers as stored, in the shape `applyTiers` takes. Like `readBranding`. */
+export declare function readTiers(opts: {
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<RepositoryTiersState>;
+/** 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 declare function readEntitlements(opts: {
+    customer: string;
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<CustomerEntitlements>;
+/** What `GET /tenant/v0/branding` answers (ADR-039): who edits the tab, and the branding a `PUT` would send back unchanged. */
+export interface RepositoryBrandingState {
+    source: TenantSource;
+    branding: RepositoryBranding;
+}
+/** What `GET /tenant/v0/portal` answers (ADR-039): who edits the tab, the options a `PUT` would send back unchanged, and the pages an administrator moved to the Tenant's application. */
+export interface RepositoryPortalState {
+    source: TenantSource;
+    portal: Record<PortalSwitch, boolean> & {
+        pages: RepositoryPortal["pages"];
+    };
+    redirected: PortalPage[];
+}
+/**
+ * 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 declare function readBranding(opts: {
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<RepositoryBrandingState>;
+/** The portal options as stored, in the shape `applyPortal` takes. Like `readBranding`. */
+export declare function readPortal(opts: {
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<RepositoryPortalState>;
+/** Report a Customer's tier (ADR-023, ADR-061), signed with a key of scope `entitlements`. */
+export declare function reportEntitlement(opts: {
+    customer: string;
+    tier: string;
+    status?: "active" | "past_due" | "canceled";
+    period_end?: string | null;
+    members?: string[];
+    key: string;
+    baseUrl: string;
+    idempotencyKey?: string;
+    fetch?: FetchLike;
+}): Promise<{
+    customer: string;
+    tier: string;
+    billing: Record<string, unknown>;
+}>;
+/** The Tenant's own tier and use (ADR-064 §11), for its server or its agent. Read-only: paying stays with people. */
+export declare function readTenantSubscription(opts: {
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<TenantSubscriptionView>;
+/** The current revision and hash, and what waits for approval. */
+export declare function definitionStatus(opts: {
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<DefinitionStatus>;
+/** What `GET /tenant/v0/engine` answers. `sdk` (ADR-074 §4): the SDK version the Engine was built with, and the oldest it still serves without a break. */
+export interface EngineInfo {
+    version: string;
+    released_at: string | null;
+    latest_changeset: number;
+    site: {
+        docs: string | null;
+        changesets: string | null;
+    };
+    /** Absent on an Engine from before ADR-074. */
+    sdk?: {
+        built_with: string;
+        minimum: string;
+    };
+}
+/** 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 declare function readEngine(opts: {
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<EngineInfo>;
+/** Every changeset after `since`, each with this Tenant's ticket and status when it has one. */
+export declare function readChangesets(opts: {
+    key: string;
+    baseUrl: string;
+    since?: number;
+    fetch?: FetchLike;
+}): Promise<{
+    latest: number;
+    changesets: TenantChangeset[];
+}>;
+/** 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 declare function setChangesetStatus(opts: {
+    key: string;
+    baseUrl: string;
+    number: number;
+    status: Exclude<ChangesetStatus, "new">;
+    applied_version?: string;
+    reason?: string;
+    note?: string;
+    fetch?: FetchLike;
+}): Promise<TenantChangeset>;
+/** 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 declare function sendFeedback(opts: {
+    key: string;
+    baseUrl: string;
+    report: FeedbackReport;
+    fetch?: FetchLike;
+}): Promise<{
+    id: string;
+    received_at: string;
+}>;
+/** The Tenant's feedback tickets that changed after the cursor, with the replies it may read; keep `next` for the next call. */
+export declare function readFeedback(opts: {
+    key: string;
+    baseUrl: string;
+    since?: string;
+    fetch?: FetchLike;
+}): Promise<{
+    items: TicketView[];
+    next: string | null;
+}>;
+/** Answer on one of the Tenant's feedback tickets. */
+export declare function replyToFeedback(opts: {
+    key: string;
+    baseUrl: string;
+    id: string;
+    body: string;
+    fetch?: FetchLike;
+}): Promise<TicketView>;
+/** What `GET /tenant/v0/key` answers: the calling key's own record. Never another key, never key material. */
+export interface TenantKeyRecord {
+    id: string;
+    name: string;
+    /** The Tenant's slug. */
+    tenant: string;
+    scopes: TenantKeyScope[];
+    created_at: string;
+    expires_at: string;
+}
+/** The calling key's own record: which Tenant it is for, what it reaches and when it expires. Any live key. */
+export declare function readKey(opts: {
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<TenantKeyRecord>;
+/** The Tenant's tags (ADR-057), with a key of scope `tags`. */
+export declare function readTags(opts: {
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<TagView[]>;
+/** What `setTag` may set on a tag. A part left out keeps its value; a new tag starts as `staff`, `slate`, with no rules and no effects. */
+export interface TagChange {
+    visibility?: TagVisibility;
+    description?: string;
+    colour?: TagColour;
+    rules?: TagRule[];
+    effects?: TagEffect[];
+}
+/** Create the tag or change it, by name, so a server keeps its tags in step. `created` says which happened. */
+export declare function setTag(opts: {
+    name: string;
+    change?: TagChange;
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<TagView & {
+    created: boolean;
+}>;
+/** Put a tag on one of the Tenant's Customers. `added` is false when the Customer had it already. */
+export declare function tagCustomer(opts: {
+    customer: string;
+    tag: string;
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<{
+    customer: string;
+    tag: string;
+    added: boolean;
+}>;
+/** Take a tag off one of the Tenant's Customers. `removed` is false when the Customer did not have it. */
+export declare function untagCustomer(opts: {
+    customer: string;
+    tag: string;
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<{
+    customer: string;
+    tag: string;
+    removed: boolean;
+}>;
+/** Which tickets `listTickets` answers with. Every part is optional; none lists the open and recent ones. */
+export interface TicketFilter {
+    status?: string;
+    /** A primary type (`issue`, `request`, `feedback`) or a secondary one. */
+    type?: string;
+    archived?: boolean;
+    unread?: boolean;
+    tags?: TagSelector;
+    limit?: number;
+}
+/** The tickets the Tenant's servers are a party of (ADR-058 §10), with a key of scope `tickets`. */
+export declare function listTickets(opts: {
+    filter?: TicketFilter;
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<TicketSummary[]>;
+/** One ticket with its posts. Reading it marks it read for the Tenant's servers. */
+export declare function readTicket(opts: {
+    id: string;
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<TicketView>;
+/** A new ticket: to the platform (`to: "platform"`, `type` one of `TENANT_PLATFORM_TYPES`) or to one of the Tenant's Customers (`to: <cst>`). */
+export interface OpenTicket {
+    to: string;
+    type?: string;
+    subject: string;
+    body: string;
+    priority?: Priority;
+    refs?: string[];
+    /** The Customer's name as the Tenant's own pages show it, kept for the lists. */
+    to_name?: string;
+}
+export declare function openTicket(opts: {
+    ticket: OpenTicket;
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<TicketView>;
+/** A reply on a ticket. `visibility: "side"` keeps it to the Tenant's own side. */
+export declare function postToTicket(opts: {
+    id: string;
+    body: string;
+    visibility?: "all" | "side";
+    refs?: string[];
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<TicketView>;
+/** One change to a ticket or an announcement: its status, its priority or archiving it. */
+export interface TicketChange {
+    status?: AnyStatus;
+    hold_until?: string | null;
+    priority?: Priority;
+    archived?: boolean;
+    audience?: TagSelector | null;
+    announcement?: AnnouncementOptions;
+}
+export declare function updateTicket(opts: {
+    id: string;
+    change: TicketChange;
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<TicketView>;
+/** An announcement's own settings (ADR-058 §8): texts per language, when it shows and how. */
+export interface AnnouncementOptions {
+    languages?: Record<string, {
+        subject: string;
+        body: string;
+    }>;
+    default_language?: string;
+    publish_at?: string | null;
+    expires_at?: string | null;
+    pinned?: boolean;
+    severity?: "info" | "warning";
+    replies?: boolean;
+}
+/** The Tenant's announcements to its Customers, with every status, and the platform's announcements to the Tenant, read only. */
+export declare function listAnnouncements(opts: {
+    lang?: string;
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<{
+    items: TicketSummary[];
+    platform: AnnouncementItem[];
+}>;
+export declare function readAnnouncement(opts: {
+    id: string;
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<TicketView>;
+/** A new announcement to the Tenant's Customers: its text, its audience of tags (everyone without one) and its own settings. */
+export interface NewAnnouncement {
+    subject: string;
+    body?: string;
+    type?: string;
+    priority?: Priority;
+    audience?: TagSelector;
+    announcement?: AnnouncementOptions;
+}
+/** 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 declare function draftAnnouncement(opts: {
+    announcement: NewAnnouncement;
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<TicketView>;
+/** Publish a draft announcement now: its status becomes `published`. */
+export declare function publishAnnouncement(opts: {
+    id: string;
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<TicketView>;
+export declare function updateAnnouncement(opts: {
+    id: string;
+    change: TicketChange;
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<TicketView>;
+/** Take a published announcement down: its status becomes `withdrawn`. */
+export declare function withdrawAnnouncement(opts: {
+    id: string;
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<TicketView>;
+/** Delete an announcement that is still a draft; a published one is withdrawn instead. */
+export declare function deleteAnnouncementDraft(opts: {
+    id: string;
+    key: string;
+    baseUrl: string;
+    fetch?: FetchLike;
+}): Promise<void>;
+export declare function b64url(bytes: Uint8Array): string;
+export declare function fromB64url(value: string): Uint8Array;
+export {};
+//# sourceMappingURL=definition-set.d.ts.map