@aplons/auth 0.1.0 → 0.2.0

package/README.md

@@ -17,14 +17,14 @@ Eine Datei, vier Adressen:
 
 ```ts
 // app/api/auth/[...aplons]/route.ts
-import { handhabe } from "@aplons/auth/next";
+import { createHandler } from "@aplons/auth/next";
 
-export const { GET, POST } = handhabe({
+export const { GET, POST } = createHandler({
   issuer: process.env.APLONS_ISSUER!,          // https://auth.aplons.com
   clientId: process.env.APLONS_CLIENT_ID!,
   clientSecret: process.env.APLONS_CLIENT_SECRET,
   redirectUri: process.env.APLONS_REDIRECT_URI!,
-  nachAnmeldung: "/",
+  afterLogin: "/",
 });
 ```
 
@@ -32,28 +32,29 @@ Das ergibt:
 
 | Adresse | wozu |
 |---|---|
-| `/api/auth/login` | Anmeldung starten. `?weiter=/pfad` merkt sich, wohin danach. |
+| `/api/auth/login` | Anmeldung starten. `?next=/pfad` merkt sich, wohin danach. |
 | `/api/auth/callback` | Rückkehr von Aplons. Hier ist nichts zu tun. |
 | `/api/auth/logout` | Abmelden — hier **und** bei Aplons. |
 | `/api/auth/me` | Wer angemeldet ist; erneuert das Token still, wenn nötig. |
+| `/api/auth/branding` | Logo, Farben und Eckenradius des Mandanten. |
 
 Ein Anmeldeknopf ist dann ein Link:
 
 ```tsx
-<a href="/api/auth/login?weiter=/rechnungen">Anmelden</a>
+<a href="/api/auth/login?next=/rechnungen">Anmelden</a>
 ```
 
 Die Sitzung in einer eigenen Route lesen:
 
 ```ts
-const { sitzungAus, auth } = handhabe({ /* … */ });
+const { getSession, auth } = createHandler({ /* … */ });
 
 export async function GET(request: Request) {
-  const sitzung = await sitzungAus(request);
-  if (!sitzung) return new Response("nicht angemeldet", { status: 401 });
+  const session = await getSession(request);
+  if (!session) return new Response("nicht angemeldet", { status: 401 });
 
-  const profil = await auth.profil(sitzung.accessToken);
-  return Response.json(profil);
+  const user = await auth.userInfo(session.accessToken);
+  return Response.json(user);
 }
 ```
 
@@ -70,19 +71,19 @@ const auth = new AplonsAuth({
 });
 
 // 1. Hinschicken
-const { url, verifier, state, nonce } = await auth.start();
+const { url, verifier, state, nonce } = await auth.startLogin();
 // verifier, state und nonce bis zur Rückkehr aufbewahren
 
 // 2. Zurückkommen
-const sitzung = await auth.rueckkehr({ url: anfrageUrl, verifier, state, nonce });
-sitzung.accessToken;
-sitzung.claims?.email;
+const session = await auth.completeLogin({ url: requestUrl, verifier, state, nonce });
+session.accessToken;
+session.claims?.email;
 
 // 3. Erneuern
-const frisch = await auth.erneuern(sitzung.refreshToken!);
+const fresh = await auth.refresh(session.refreshToken!);
 
 // 4. Abmelden
-const abmelden = await auth.abmeldeUrl({ danach: "https://app.example.de/" });
+const logout = await auth.logoutUrl({ returnTo: "https://app.example.de/" });
 ```
 
 **`verifier`, `state` und `nonce` gehören in ein kurzlebiges, `httpOnly`
@@ -90,10 +91,53 @@ gesetztes Cookie — nicht in den `localStorage`.** Was dort liegt, liest jedes
 Skript auf der Seite, und mit dem Verifier lässt sich ein abgefangener
 Anmeldecode einlösen. Der Next-Teil oben macht das schon richtig.
 
+## Aussehen wie die Firma
+
+Eine angebundene Anwendung meldet Leute nicht nur an, sie zeigt ihnen danach
+etwas. Ein Intranet-Hub, ein internes Werkzeug, ein Kundenportal: alle sollen
+aussehen wie die Firma, für die sie gebaut sind. Das Logo dafür ein zweites
+Mal einzupflegen ist die Art Arbeit, die genau einmal gemacht und beim
+nächsten Rebranding vergessen wird — dann trägt die Anmeldung das neue Logo
+und der Hub daneben das alte.
+
+Also von dort, wo es ohnehin gepflegt wird:
+
+```ts
+const branding = await auth.branding(session.accessToken);
+
+branding.logoUrl;            // vollständige Adresse, direkt für ein <img>
+branding.colors.primary;     // "#4882fe"
+branding.radius;             // 8
+branding.tenant.name;        // "Muster GmbH"
+```
+
+Als CSS-Variablen, wenn die ganze Oberfläche sie tragen soll:
+
+```tsx
+import { brandingCss } from "@aplons/auth";
+
+<style>{brandingCss(branding)}</style>
+<button style={{ background: "var(--aplons-primary)", borderRadius: "var(--aplons-radius)" }}>
+```
+
+Mit Next.js geht es auch ohne eigenen Aufruf: `/api/auth/branding` liefert
+dasselbe für die angemeldete Sitzung, und `getBranding(request)` holt es in
+einer eigenen Route.
+
+Zwei Dinge müssen dafür stimmen, und die Fehlermeldung sagt welches:
+
+| `code` | heißt |
+|---|---|
+| `insufficient_scope` | Dein Token trägt den Scope `branding` nicht — trag ihn bei der Anwendung ein und fordere ihn an (`scope: ["openid", "profile", "email", "branding"]`). |
+| `branding_not_shared` | Der Mandant gibt sein Erscheinungsbild nicht heraus. Das steht in **seinen** Richtlinien und ist ab Werk aus; nur er kann das ändern. |
+
+**Speichere das Ergebnis zwischen.** Ein Logo wechselt selten, und eine Seite,
+die es bei jedem Aufruf neu holt, wartet dafür jedes Mal auf das Netz.
+
 ## Eine API dahinter absichern
 
 ```ts
-const claims = await auth.pruefeToken(token);
+const claims = await auth.verifyAccessToken(token);
 claims.sub;   // das Konto
 claims.tid;   // der Mandant
 claims.rls;   // Rollen im Mandanten
@@ -123,9 +167,9 @@ Meldung für den Menschen:
 import { AplonsError } from "@aplons/auth";
 
 try {
-  await auth.rueckkehr({ /* … */ });
-} catch (fehler) {
-  if (fehler instanceof AplonsError && fehler.code === "invalid_grant") {
+  await auth.completeLogin({ /* … */ });
+} catch (error) {
+  if (error instanceof AplonsError && error.code === "invalid_grant") {
     // meistens: die Rückkehr wurde zweimal ausgeführt
   }
 }
@@ -142,9 +186,21 @@ Häufig:
 
 ## Bereiche
 
-`openid`, `profile`, `email`, `phone`, `roles`, `app_profile`. Voreinstellung
-sind die ersten drei. `roles` liefert die Rollen des Kontos **in dieser
-Anwendung**, `app_profile` deren eigene Felder — beide über `auth.profil()`.
+`openid`, `profile`, `email`, `phone`, `roles`, `app_profile`, `branding`,
+`offline_access`. Voreinstellung sind die ersten drei. `roles` liefert die
+Rollen des Kontos **in dieser Anwendung**, `app_profile` deren eigene Felder —
+beide über `auth.userInfo()`. `branding` das Erscheinungsbild des Mandanten,
+über `auth.branding()`.
+
+`offline_access` darf jeder Client anfordern, auch ohne ihn eingetragen zu
+haben, und bewirkt nichts: ein Refresh-Token kommt beim Tausch des
+Anmeldecodes ohnehin immer zurück. Er steht hier, weil er der übliche Weg
+ist, danach zu fragen, und manche Bibliotheken ihn von sich aus mitschicken.
+
+Alle anderen Bereiche muss die Anwendung im Mandanten eingetragen haben.
+Fehlt einer, kommt von `/oauth/authorize` ein `invalid_scope` zurück, dessen
+Text zwischen „kennt der Server nicht" und „diese Anwendung hat ihn nicht
+eingetragen" unterscheidet.
 
 ## Sitzungen ablegen
 
@@ -153,12 +209,16 @@ Speicher aus, hat aber zwei Grenzen: 4 KB, und ein Widerruf wirkt erst, wenn
 das Zugriffstoken abläuft. Wer eine Datenbank hat, gibt seine eigene Ablage an:
 
 ```ts
-handhabe({
+createHandler({
   /* … */
-  speicher: {
-    async lies(id) { /* … */ },
-    async schreib(id, sitzung) { /* … */ },
-    async loesche(id) { /* … */ },
+  store: {
+    async read(id) { /* … */ },
+    async write(id, session) { /* … */ },
+    async delete(id) { /* … */ },
   },
 });
 ```
+
+Alle drei werden gebraucht: `delete` beim Abmelden, `write` bei jeder stillen
+Erneuerung — und zwar unter **derselben** Kennung, damit aus einer Sitzung
+nicht alle zehn Minuten eine weitere Zeile wird.

package/dist/branding.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Das Erscheinungsbild des Mandanten — Logo, Farben, Eckenradius.
+ *
+ * Eine angebundene Anwendung meldet Leute nicht nur an, sie zeigt ihnen
+ * danach etwas. Ein Intranet-Hub, ein internes Werkzeug, ein Kundenportal:
+ * alle sollen aussehen wie die Firma, für die sie gebaut sind. Das Logo dafür
+ * ein zweites Mal einzupflegen ist die Art von Arbeit, die genau einmal
+ * gemacht und danach beim Rebranding vergessen wird — dann trägt die
+ * Anmeldung das neue Logo und der Hub daneben das alte.
+ *
+ * Also von dort, wo es ohnehin gepflegt wird:
+ *
+ *   const branding = await auth.branding(session.accessToken);
+ *   branding.logoUrl;
+ *   branding.colors.primary;
+ *
+ * Zwei Dinge müssen dafür stimmen, und die Fehlermeldung sagt welches:
+ * die Anwendung braucht den Bereich `branding`, und der Mandant muss das
+ * Weitergeben in seinen Richtlinien erlaubt haben. Letzteres ist ab Werk aus.
+ */
+/** Was `auth.branding()` zurückgibt. */
+export type Branding = {
+    tenant: {
+        slug: string;
+        /** Anzeigename des Mandanten. */
+        name: string;
+        /** Der oberste Mandant darüber — für „bereitgestellt von". */
+        rootName: string;
+    };
+    logoUrl?: string;
+    /** Fassung für dunkle Oberflächen, falls hinterlegt. */
+    logoUrlDark?: string;
+    faviconUrl?: string;
+    /**
+     * Gesetzt heißt: der Mandant legt hell oder dunkel fest. Fehlt der Wert,
+     * entscheidet die Anwendung — in aller Regel: was der Besucher eingestellt
+     * hat.
+     */
+    colorScheme?: "light" | "dark";
+    colors: {
+        primary: string;
+        /** Was auf der Primärfarbe lesbar ist. */
+        primaryText: string;
+        background: string;
+        surface: string;
+        text: string;
+        mutedText: string;
+        border: string;
+        danger: string;
+    };
+    /** Eckenradius in Pixeln. */
+    radius: number;
+    logo: {
+        height: number;
+        maxWidth: number;
+        /** Steht der Name neben dem Logo? Fehlt der Wert: Sache der Anwendung. */
+        showText?: boolean;
+        /** Was dort steht, wenn nicht der Mandantenname. */
+        text?: string;
+    };
+    imprintUrl?: string;
+    privacyUrl?: string;
+    supportEmail?: string;
+};
+/**
+ * Die Farben und der Eckenradius als CSS-Variablen.
+ *
+ * Gedacht für ein `<style>` im Kopf der Seite oder für ein `style`-Attribut
+ * am äußersten Element:
+ *
+ *   <style>{brandingCss(branding)}</style>
+ *   …
+ *   <button style={{ background: "var(--aplons-primary)" }}>
+ *
+ * Nur Farben und Radius: ein Logo ist ein Bild und gehört in ein `<img>`, wo
+ * es einen Alternativtext bekommt, statt als Hintergrund in einem Stylesheet
+ * zu verschwinden.
+ */
+export declare function brandingCss(branding: Branding, options?: {
+    /** Woran die Variablen hängen. Voreinstellung `:root`. */
+    selector?: string;
+}): string;

package/dist/branding.js

@@ -0,0 +1,80 @@
+/**
+ * Das Erscheinungsbild des Mandanten — Logo, Farben, Eckenradius.
+ *
+ * Eine angebundene Anwendung meldet Leute nicht nur an, sie zeigt ihnen
+ * danach etwas. Ein Intranet-Hub, ein internes Werkzeug, ein Kundenportal:
+ * alle sollen aussehen wie die Firma, für die sie gebaut sind. Das Logo dafür
+ * ein zweites Mal einzupflegen ist die Art von Arbeit, die genau einmal
+ * gemacht und danach beim Rebranding vergessen wird — dann trägt die
+ * Anmeldung das neue Logo und der Hub daneben das alte.
+ *
+ * Also von dort, wo es ohnehin gepflegt wird:
+ *
+ *   const branding = await auth.branding(session.accessToken);
+ *   branding.logoUrl;
+ *   branding.colors.primary;
+ *
+ * Zwei Dinge müssen dafür stimmen, und die Fehlermeldung sagt welches:
+ * die Anwendung braucht den Bereich `branding`, und der Mandant muss das
+ * Weitergeben in seinen Richtlinien erlaubt haben. Letzteres ist ab Werk aus.
+ */
+/** Die Namen, unter denen `brandingCss` die Werte ablegt. */
+const VARIABLES = [
+    ["primary", "primary"],
+    ["primaryText", "primary-text"],
+    ["background", "background"],
+    ["surface", "surface"],
+    ["text", "text"],
+    ["mutedText", "muted-text"],
+    ["border", "border"],
+    ["danger", "danger"],
+];
+/**
+ * Genau eine Hex-Farbe, sonst nichts.
+ *
+ * Der Server prüft das schon. Hier wird es trotzdem geprüft, weil das
+ * Ergebnis in ein `<style>` geschrieben wird: käme dort jemals ein anderer
+ * Text an — durch einen Zwischenspeicher, einen Vermittlungsserver, eine
+ * spätere Änderung am Server —, stünde er in einem Stylesheet, und ein
+ * Stylesheet lässt sich zum Auslesen von Eingaben missbrauchen. Eine Prüfung,
+ * die an zwei Stellen steht, kostet nichts; eine, die nur an einer steht,
+ * kostet genau dann etwas, wenn diese eine sich ändert.
+ */
+function hex(value) {
+    return typeof value === "string" && /^#[0-9a-fA-F]{6}$/.test(value)
+        ? value.toLowerCase()
+        : null;
+}
+/**
+ * Die Farben und der Eckenradius als CSS-Variablen.
+ *
+ * Gedacht für ein `<style>` im Kopf der Seite oder für ein `style`-Attribut
+ * am äußersten Element:
+ *
+ *   <style>{brandingCss(branding)}</style>
+ *   …
+ *   <button style={{ background: "var(--aplons-primary)" }}>
+ *
+ * Nur Farben und Radius: ein Logo ist ein Bild und gehört in ein `<img>`, wo
+ * es einen Alternativtext bekommt, statt als Hintergrund in einem Stylesheet
+ * zu verschwinden.
+ */
+export function brandingCss(branding, options) {
+    const declarations = [];
+    for (const [key, name] of VARIABLES) {
+        const value = hex(branding.colors?.[key]);
+        if (value)
+            declarations.push(`--aplons-${name}: ${value};`);
+    }
+    const radius = Number(branding.radius);
+    if (Number.isFinite(radius)) {
+        declarations.push(`--aplons-radius: ${Math.min(Math.max(Math.round(radius), 0), 64)}px;`);
+    }
+    if (declarations.length === 0)
+        return "";
+    // Der Selektor kommt vom Aufrufer, nicht vom Server — trotzdem ohne
+    // geschweifte Klammern, damit ein Tippfehler nicht mitten im Block einen
+    // neuen aufmacht.
+    const selector = (options?.selector ?? ":root").replace(/[{}]/g, "");
+    return `${selector} { ${declarations.join(" ")} }`;
+}

package/dist/client.d.ts

@@ -1,16 +1,16 @@
 /**
- * Die Anbindung an Aplons.
+ * The connection to Aplons.
  *
- * Vier Schritte, mehr ist es nicht: Anmeldung starten, Rückkehr entgegen-
- * nehmen, Token erneuern, abmelden. Dazu das Prüfen eines Tokens für den,
- * der eine API dahinter absichert.
+ * Four steps, no more: start the login, complete it, refresh the tokens, log
+ * out. Plus verifying a token, for whoever has an API behind it.
  *
- * Alles, was der Ablauf sonst noch braucht — welcher Endpunkt wo liegt,
- * welche Schlüssel gerade gültig sind —, holt sich das Paket selbst. Wer nur
- * `issuer` und `clientId` kennt, ist fertig.
+ * Everything else the flow needs — which endpoint lives where, which keys are
+ * currently valid — the package fetches itself. If you know `issuer` and
+ * `clientId`, you are done.
  */
-import { type Metadaten } from "./discovery.js";
-import type { AccessTokenClaims, Anmeldevorgang, AplonsOptions, Profil, Sitzung } from "./types.js";
+import { type Metadata } from "./discovery.js";
+import type { Branding } from "./branding.js";
+import type { AccessTokenClaims, AplonsOptions, AuthorizationRequest, Session, UserInfo } from "./types.js";
 export declare class AplonsAuth {
     #private;
     readonly issuer: string;
@@ -19,75 +19,98 @@ export declare class AplonsAuth {
     readonly scope: string[];
     constructor(options: AplonsOptions);
     /**
-     * Die Endpunkte, einmal geholt und dann behalten.
+     * The endpoints, fetched once and then kept.
      *
-     * Als Versprechen zwischengespeichert, nicht als Ergebnis: sonst holen
-     * zehn gleichzeitige Anfragen beim Start zehnmal dieselbe Datei.
+     * Cached as a promise, not as a result: otherwise ten concurrent requests
+     * at startup fetch the same document ten times.
      */
-    metadaten(): Promise<Metadaten>;
+    metadata(): Promise<Metadata>;
     /**
-     * Schritt 1: Wohin der Browser geschickt wird.
+     * Step 1: where to send the browser.
      *
-     * `verifier` und `state` müssen bis zur Rückkehr aufbewahrt werden — in
-     * einem kurzlebigen, `httpOnly`-Cookie, nicht im localStorage: was dort
-     * liegt, liest jedes Skript auf der Seite.
+     * `verifier`, `state` and `nonce` have to survive until the callback — in a
+     * short-lived, `httpOnly` cookie, not in localStorage: whatever sits there
+     * is readable by every script on the page.
      */
-    start(options?: {
-        /** Überschreibt die Bereiche aus dem Konstruktor. */
+    startLogin(options?: {
+        /** Overrides the scopes from the constructor. */
         scope?: string[];
-        /** Wird unverändert zurückgegeben — etwa die Seite, die aufgerufen war. */
-        zusatz?: Record<string, string>;
-        /** Erzwingt die Anmeldemaske, auch wenn schon eine Sitzung besteht. */
-        erneutAnmelden?: boolean;
-        /** Setzt die Anmeldeseite auf diesen Mandanten. */
+        /** Passed through unchanged — e.g. the page that was being opened. */
+        extraParams?: Record<string, string>;
+        /** Forces the login screen even when a session already exists. */
+        forceLogin?: boolean;
+        /** Puts the login screen on this tenant. */
         tenant?: string;
-    }): Promise<Anmeldevorgang>;
+    }): Promise<AuthorizationRequest>;
     /**
-     * Schritt 2: Die Rückkehr.
+     * Step 2: the callback.
      *
-     * Nimmt den vollständigen URL entgegen, mit dem der Browser zurückkam, und
-     * die beiden Werte aus Schritt 1.
+     * Takes the full URL the browser came back with, plus the values from
+     * step 1.
      */
-    rueckkehr(options: {
-        /** Der Aufruf-URL, komplett. */
+    completeLogin(options: {
+        /** The incoming URL, complete. */
         url: string | URL;
         verifier: string;
-        /** Der State aus Schritt 1 — wird gegen den im URL geprüft. */
+        /** The state from step 1 — checked against the one in the URL. */
         state: string;
-        /** Der Nonce aus Schritt 1, wenn ein ID-Token erwartet wird. */
+        /** The nonce from step 1, when an ID token is expected. */
         nonce?: string;
-    }): Promise<Sitzung>;
-    /** Schritt 3: Ein abgelaufenes Zugriffstoken gegen ein frisches tauschen. */
-    erneuern(refreshToken: string): Promise<Sitzung>;
+    }): Promise<Session>;
+    /** Step 3: trade an expired access token for a fresh one. */
+    refresh(refreshToken: string): Promise<Session>;
     /**
-     * Schritt 4: Abmelden — bei Aplons, nicht nur hier.
+     * Step 4: log out — at Aplons, not just here.
      *
-     * Nur die eigene Sitzung zu löschen genügt nicht: die Sitzung bei Aplons
-     * bliebe bestehen, und die nächste Anmeldung liefe ohne Passwort durch.
-     * Auf einem geteilten Rechner ist das der Unterschied zwischen abgemeldet
-     * und scheinbar abgemeldet.
+     * Clearing your own session is not enough: the session at Aplons would
+     * survive, and the next login would sail through without a password. On a
+     * shared machine that is the difference between signed out and apparently
+     * signed out.
      */
-    abmeldeUrl(options?: {
-        /** Wohin Aplons nach dem Abmelden zurückschickt. Muss hinterlegt sein. */
-        danach?: string;
-        /** Das ID-Token der Sitzung; damit weiß Aplons, wen es abmeldet. */
+    logoutUrl(options?: {
+        /** Where Aplons sends the browser after logging out. Must be registered. */
+        returnTo?: string;
+        /** The session's ID token; it tells Aplons who is being logged out. */
         idToken?: string;
     }): Promise<string>;
     /**
-     * Ein Zugriffstoken prüfen — für den, der eine eigene API dahinter hat.
+     * Verify an access token — for whoever has their own API behind it.
      *
-     * Geprüft wird gegen die öffentlichen Schlüssel von Aplons, ohne Rückfrage
-     * bei jedem Aufruf: Unterschrift, Aussteller und Ablauf. Das ist der
-     * Unterschied zwischen „das Token sieht echt aus" und „das Token ist echt".
+     * Checked against the public keys of Aplons, without a round trip on every
+     * call: signature, issuer and expiry. That is the difference between "the
+     * token looks real" and "the token is real".
      */
-    pruefeToken(token: string): Promise<AccessTokenClaims>;
-    /** Die Angaben zum angemeldeten Konto, so weit die Bereiche es hergeben. */
-    profil(accessToken: string): Promise<Profil>;
+    verifyAccessToken(token: string): Promise<AccessTokenClaims>;
     /**
-     * Ein Refresh-Token entwerten.
+     * Das Erscheinungsbild des Mandanten — Logo, Farben, Eckenradius.
      *
-     * Gehört zum Abmelden dazu: ein Token, das noch dreißig Tage gilt, wird
-     * vom Löschen des Cookies nicht ungültig.
+     * Ein Aufruf, damit eine eingebundene Oberfläche aussieht wie die Firma,
+     * für die sie gebaut ist, statt deren Logo ein zweites Mal zu pflegen:
+     *
+     *   const branding = await auth.branding(session.accessToken);
+     *
+     * Welcher Mandant, steht im Token — nicht im Aufruf. Ein Konto bekommt
+     * damit immer genau das Erscheinungsbild, das es auf der Anmeldeseite auch
+     * gesehen hat.
+     *
+     * Es lohnt sich, das Ergebnis zwischenzuspeichern: ein Logo wechselt selten,
+     * und eine Seite, die es bei jedem Aufruf neu holt, wartet dafür jedes Mal
+     * auf eine Antwort aus dem Netz.
+     *
+     * Zwei Absagen sind möglich und meinen Verschiedenes: `insufficient_scope`
+     * heißt, das Token trägt den Bereich `branding` nicht — dann fehlt er in den
+     * `scope`s dieser Anwendung. `branding_not_shared` heißt, der Mandant gibt
+     * sein Erscheinungsbild nicht heraus; das steht in seinen Richtlinien und
+     * ist ab Werk aus.
+     */
+    branding(accessToken: string): Promise<Branding>;
+    /** The details of the signed-in account, as far as the scopes allow. */
+    userInfo(accessToken: string): Promise<UserInfo>;
+    /**
+     * Revoke a refresh token.
+     *
+     * Part of logging out: a token still valid for thirty days does not become
+     * invalid because a cookie was deleted.
      */
-    widerrufen(refreshToken: string): Promise<void>;
+    revoke(refreshToken: string): Promise<void>;
 }