initiative-plugin-sdk 2.0.0

package/dist/client.d.ts

@@ -0,0 +1,288 @@
+/**
+ * Initiative, as a plug-in reaches it.
+ *
+ * A plug-in authenticates with its own key (`private_key_jwt`, RFC 7523) at
+ * `POST {baseUrl}/plugin-platform/oauth/token` and acts with one of two tokens:
+ *
+ * - an **installation token** (`client_credentials` + `installation`), acting as
+ *   the community that installed the plug-in, with the scopes it granted;
+ * - a **member token** (the JWT-bearer grant, RFC 7523 §2.1), acting for one
+ *   member, within what that member consented to.
+ *
+ * Either can be narrowed to one initiative the plug-in is placed in (RFC 8707) and
+ * to fewer scopes (RFC 6749 §3.3). {@link Initiative.asInstallation} and
+ * {@link Initiative.asMember} each give a {@link Client} acting that way; a
+ * handler is handed one already acting for its call. {@link Client.api} holds
+ * a typed method for every route Initiative's plug-in API describes, generated
+ * from that description.
+ *
+ * Tokens are opaque and never read. The token response says how long each
+ * lives and which scopes it holds: a call needing a scope the token does not
+ * hold fails before it is sent, naming the scope. Tokens are cached until 30
+ * seconds before they expire, concurrent callers share one request, and a
+ * call answered 401 is sent once more on a fresh token.
+ */
+import { PluginApi } from "./plugin-api.generated.js";
+import type { ActorKind, PluginScope, Scope } from "./contract.js";
+import type { Actor } from "./define.js";
+import { type PluginSigningKey } from "./keys.js";
+export { generatePluginKeys, jwkThumbprint, loadPrivateKey, publicJwks, type PluginKeyAlgorithm, type PluginSigningKey, type GeneratedPluginKeys, type Jwks, type PublicJwk, } from "./keys.js";
+export type { PluginApi, PluginApiSchemas } from "./plugin-api.generated.js";
+export interface InitiativeOptions {
+    /** The deployment's API base, such as `https://initiative.example.com/api/v1`. */
+    baseUrl: string;
+    /** The plug-in's public id: its OAuth client id. */
+    publicId: string;
+    /** The plug-in's key, as `loadPrivateKey` gives it. */
+    key: PluginSigningKey;
+    fetch?: typeof fetch;
+    /** Milliseconds since the epoch. */
+    now?: () => number;
+}
+/** Narrowing for a token: fewer scopes than were granted, and one initiative. */
+export interface Narrowing {
+    scopes?: ReadonlyArray<Scope | PluginScope>;
+    initiative?: number;
+}
+/**
+ * A standing beyond the plug-in's own reach, which a community grants with its
+ * scope: `moderator` (`initiatives:moderate`) in the one initiative the token
+ * is narrowed to, or `community_admin` (`community:admin`) across the community.
+ */
+export type InstallLevel = "moderator" | "community_admin";
+export interface InstallationOptions extends Narrowing {
+    /** Absent: the plug-in's own reach. */
+    level?: InstallLevel;
+}
+export interface MemberOptions extends Narrowing {
+    /** The purpose the member consented to. Absent: consent to the whole plug-in. */
+    purpose?: string;
+}
+/** One community that has installed the plug-in. */
+export interface Installation {
+    installation: string;
+    /** False while it is switched off or its community is on hold: keep what you hold for it. */
+    active: boolean;
+}
+/** What another plug-in answered, through Initiative. */
+export interface InvokeOutcome {
+    endpoint: string;
+    actor: ActorKind;
+    result: Record<string, unknown>;
+}
+/** One member's stored values, by the handle the plug-in knows. */
+export interface MemberConnectionConfig {
+    connectionId: string;
+    connectionRef: string;
+    status: string;
+    values: Record<string, unknown>;
+}
+/**
+ * The installation's configuration: each community-wide connection's values
+ * and the managed values of each member's. Vendor tokens are never in it; ask
+ * for one with {@link Client.connectionToken}. Hold it in memory only.
+ */
+export interface InstallationConfig {
+    communityRef: string;
+    installId: number;
+    listingUid: string;
+    listingVersion: string;
+    enabled: boolean;
+    /** The plug-in's last verdict on this configuration: `unverified`, `ok` or `invalid`. */
+    configState: string;
+    configStateDetail: string | null;
+    /** Whether an admin still has a community-wide connection to fill in. */
+    needsConfig: boolean;
+    /** Connection id → field key → value. */
+    connections: Record<string, Record<string, unknown>>;
+    /** Connection id → the handle of each community-wide connection that has one. */
+    connectionRefs: Record<string, string>;
+    memberConnections: MemberConnectionConfig[];
+}
+/** One member's connection, with its state and no values. */
+export interface InstallationConnection {
+    connectionId: string;
+    connectionRef: string;
+    status: string;
+    blocked: boolean;
+    accountLabel: string | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** A vendor access token for one connection. Send it to the vendor; never store it. */
+export interface ConnectionAccessToken {
+    accessToken: string;
+    /** Milliseconds since the epoch, or null when the vendor did not say. */
+    expiresAt: number | null;
+}
+export interface ConfigStatusReport {
+    state: "ok" | "invalid";
+    /** A short code shown beside `invalid`, such as `missing_scope`. */
+    detail?: string;
+}
+export interface ConfigStatus {
+    communityRef: string;
+    installId: number;
+    configState: string;
+    configStateDetail: string | null;
+}
+export interface InstallationEvent {
+    /** An `emit` endpoint the plug-in declares, by its manifest id. */
+    eventType: string;
+    /** At most 8 KiB as JSON. */
+    payload?: Record<string, unknown>;
+    /** The initiative the event is about, when it is about one. */
+    initiativeId?: number;
+}
+export interface ConsentRequest {
+    member: string;
+    /** The plug-in's own id for what the member is consenting to. Absent: the whole plug-in. */
+    purpose?: string;
+    /** Shown to the member as the plug-in's own words. */
+    label: string;
+    initiativeId?: number;
+    /** What the plug-in asks for. The member may grant less. */
+    access: "read" | "read_write";
+}
+/** The token endpoint refused (RFC 6749 §5.2). */
+export declare class InitiativeAuthError extends Error {
+    /** `invalid_client`, `invalid_grant`, `invalid_scope`, … */
+    readonly error: string;
+    readonly errorDescription: string | undefined;
+    readonly status: number;
+    constructor(
+    /** `invalid_client`, `invalid_grant`, `invalid_scope`, … */
+    error: string, errorDescription: string | undefined, status: number);
+}
+/** The member has not consented to this purpose, or no longer can be acted for. */
+export declare class ConsentRequiredError extends InitiativeAuthError {
+    constructor(errorDescription: string | undefined, status: number);
+}
+/** A call to Initiative answered with an error status. */
+export declare class InitiativeApiError extends Error {
+    readonly status: number;
+    /** Initiative's machine-readable `detail`, when the body carried one. */
+    readonly detail: unknown;
+    constructor(status: number, 
+    /** Initiative's machine-readable `detail`, when the body carried one. */
+    detail: unknown);
+}
+/**
+ * A call needs a scope the token does not hold. Nothing was sent. When any one
+ * of several would do, `scope` lists them, separated by spaces.
+ */
+export declare class MissingScopeError extends Error {
+    readonly scope: string;
+    constructor(scope: string);
+}
+/** Whether `held` covers `scope`. Writing implies reading. */
+export declare function grants(held: readonly string[], scope: string): boolean;
+interface Grant {
+    installation: string;
+    member?: string;
+    purpose?: string;
+    scopes: string[];
+    initiative?: number;
+    level?: InstallLevel;
+}
+interface AccessToken {
+    token: string;
+    scopes: string[];
+    expiresAt: number;
+}
+/** Issues, caches and spends the plug-in's tokens. */
+declare class Tokens {
+    private readonly options;
+    readonly baseUrl: string;
+    readonly endpoint: string;
+    private readonly cache;
+    private readonly inflight;
+    readonly fetch: typeof fetch;
+    readonly now: () => number;
+    constructor(options: InitiativeOptions);
+    /** A token for the grant, from the cache while it is fresh. */
+    token(grant: Grant | null): Promise<AccessToken>;
+    /**
+     * `fetch` against the API on the grant's token. A 401 drops the token and the
+     * call is sent once more on a fresh one.
+     */
+    send(grant: Grant | null, url: string, init: RequestInit): Promise<Response>;
+    private issue;
+    /** A signed assertion addressed to the token endpoint. */
+    private assertion;
+}
+/** Initiative, for one plug-in on one deployment. */
+export declare class Initiative {
+    private readonly tokens;
+    constructor(options: InitiativeOptions);
+    /**
+     * Every community that has installed the plug-in, following Initiative's
+     * `Link` pages to the end. One that is gone is not listed.
+     */
+    installations(): Promise<Installation[]>;
+    /** The plug-in acting as the community that installed it. */
+    asInstallation(installation: string, options?: InstallationOptions): Client;
+    /** The plug-in acting for one member, within what they consented to. */
+    asMember(installation: string, member: string, options?: MemberOptions): Client;
+}
+/**
+ * Initiative, acting as one actor in one installation.
+ *
+ * Content calls ({@link Client.request}, {@link Client.callPlugin}) go on the
+ * actor's own token. The installation's own configuration, connections, status
+ * and events go on the installation's token, narrowed to the same initiative.
+ */
+export declare class Client {
+    private readonly tokens;
+    private readonly grant;
+    private pluginApi?;
+    constructor(tokens: Tokens, grant: Grant);
+    /**
+     * Every route Initiative's plug-in API describes, as a typed method on the
+     * actor's token: `client.api.updateTask({ path: { task_id: 7 }, body })`.
+     * Each is checked against the token's scopes before it is sent, like
+     * {@link Client.request}.
+     */
+    get api(): PluginApi;
+    get installation(): string;
+    get actor(): Actor;
+    get initiative(): number | null;
+    /** The scopes the actor's token holds. */
+    scopes(): Promise<string[]>;
+    /**
+     * One call to a community route, the path after `/c/{community}`, on the actor's
+     * token. It is not sent unless the token holds `scope`. Answers the parsed
+     * JSON body (a `Blob` when the answer is not JSON), or throws
+     * {@link InitiativeApiError}.
+     */
+    request<T = unknown>(method: string, path: string, options: {
+        scope: Scope | PluginScope;
+        body?: unknown;
+    }): Promise<T>;
+    /**
+     * Call another plug-in's public endpoint through Initiative, as this actor. Needs
+     * `plugins:<publicId>`. A write is sent once and never retried by Initiative.
+     */
+    callPlugin(publicId: string, endpointId: string, params?: Record<string, unknown>): Promise<InvokeOutcome>;
+    /** The installation's configuration. */
+    config(): Promise<InstallationConfig>;
+    /** The installation's member connections: which handles are live, with no values. */
+    connections(): Promise<InstallationConnection[]>;
+    /**
+     * A usable vendor access token for one connection, by its handle. Initiative
+     * refreshes it, or mints it for a `jwt_bearer` connection. Ask each time.
+     */
+    connectionToken(connectionRef: string): Promise<ConnectionAccessToken>;
+    /** Tell Initiative whether the configuration the plug-in was handed works. */
+    reportConfigStatus(report: ConfigStatusReport): Promise<ConfigStatus>;
+    /** Emit one of the plug-in's declared events, for Initiative to keep and deliver. */
+    emitEvent(event: InstallationEvent): Promise<void>;
+    /** Ask a member to let the plug-in act for them, on Initiative's own consent screen. */
+    requestConsent(request: ConsentRequest): Promise<Record<string, unknown>>;
+    /** One operation of the plug-in API, its scope resolved from the operations table. */
+    private operation;
+    private installationGrant;
+    private installationCall;
+    private call;
+    private send;
+}