@stellar-agent-services/provider-kit 0.0.0-stage → 0.1.0

package/dist/approve/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><defs><linearGradient id="g" x1="0" y1="0" x2="1" y2="1"><stop offset="0" stop-color="#6366f1"/><stop offset="1" stop-color="#4338ca"/></linearGradient></defs><rect width="32" height="32" rx="9" fill="url(#g)"/><path d="M16 26s7-3.5 7-8.75V11l-7-2.6L9 11v6.25C9 22.5 16 26 16 26z" fill="none" stroke="#fff" stroke-width="2" stroke-linejoin="round"/><path d="m12.8 16.6 2.2 2.2 4.2-4.2" fill="none" stroke="#fff" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>

package/dist/approve/index.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="color-scheme" content="light dark" />
+    <meta name="referrer" content="no-referrer" />
+    <meta name="description" content="Approve provider-kit's transactions in your own Stellar wallet. provider-kit never sees your key." />
+    <!-- provider-kit serves this page with its Content Security Policy as a header (src/cli/approval.ts). -->
+    <title>Approve in your wallet · Provider Kit</title>
+    <link rel="icon" href="./favicon.svg" type="image/svg+xml" />
+    <script type="module" crossorigin src="./assets/index-CL28cSJy.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-BazIJAI2.css">
+  </head>
+  <body>
+    <div id="app"></div>
+  </body>
+</html>

package/dist/cli/approval-view.d.ts

@@ -0,0 +1,80 @@
+export type ApprovalState = "connect" | "working" | "review" | "done" | "failed" | "cancelled";
+/** One row of a summary: a label and its value. */
+export interface ApprovalDetail {
+    label: string;
+    value: string;
+    /** Monospace, for addresses, hashes and ids. */
+    mono?: boolean;
+    /** Where the value can be looked up, such as an account on Stellar Expert. */
+    href?: string;
+}
+export interface ApprovalStepView {
+    id: string;
+    title: string;
+    status: "pending" | "active" | "done";
+    /** What happened, once done, such as "Agent 42". */
+    note?: string;
+    /** The transaction that did it, once done. */
+    transaction?: {
+        hash: string;
+        url: string;
+    };
+}
+/** The transaction waiting for approval. */
+export interface ApprovalReview {
+    stepId: string;
+    title: string;
+    /** What signing it does, in plain words. */
+    summary: string;
+    details: ApprovalDetail[];
+    /** The transaction to sign as it is: base64 XDR. */
+    xdr: string;
+    /** Its hash, hex. Wallets that show a hash show this one. */
+    hash: string;
+    /** The most it can cost in network fees, such as "0.0012 XLM". */
+    maxFee: string;
+    /** When the network stops accepting it, in epoch milliseconds. */
+    expiresAt: number;
+}
+export interface ApprovalView {
+    /** The command that opened the page, such as "provider-kit register". */
+    command: string;
+    title: string;
+    intro: string;
+    network: {
+        id: string;
+        name: string;
+        passphrase: string;
+    };
+    /** The account to connect, when the command needs a particular one. */
+    account?: {
+        address: string;
+        label: string;
+        reason: string;
+    };
+    /** The account the wallet connected, and the wallet's name. */
+    connected?: {
+        address: string;
+        wallet?: string;
+    };
+    state: ApprovalState;
+    /** What is happening while the state is "working". */
+    activity?: string;
+    /** The steps after connecting a wallet, in order. */
+    steps: ApprovalStepView[];
+    /** Set while the state is "review". */
+    review?: ApprovalReview;
+    /** The last problem. `retry` is what the page offers: connect a wallet again, build the transaction again, or nothing. */
+    error?: {
+        title: string;
+        message: string;
+        retry: "connect" | "rebuild" | "none";
+    };
+    /** How the session ended: set once the state is "done", "failed" or "cancelled". */
+    result?: {
+        title: string;
+        message: string;
+        details: ApprovalDetail[];
+    };
+}
+//# sourceMappingURL=approval-view.d.ts.map

package/dist/cli/approval-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-view.d.ts","sourceRoot":"","sources":["../../src/cli/approval-view.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,GAAG,WAAW,CAAC;AAE/F,mDAAmD;AACnD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8EAA8E;IAC9E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;IACtC,oDAAoD;IACpD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,WAAW,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7C;AAED,4CAA4C;AAC5C,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAC1D,uEAAuE;IACvE,OAAO,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7D,+DAA+D;IAC/D,SAAS,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,KAAK,EAAE,aAAa,CAAC;IACrB,sDAAsD;IACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,qDAAqD;IACrD,KAAK,EAAE,gBAAgB,EAAE,CAAC;IAC1B,uCAAuC;IACvC,MAAM,CAAC,EAAE,cAAc,CAAC;IACxB,0HAA0H;IAC1H,KAAK,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAA;KAAE,CAAC;IAClF,oFAAoF;IACpF,MAAM,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,cAAc,EAAE,CAAA;KAAE,CAAC;CACxE"}

package/dist/cli/approval-view.js

@@ -0,0 +1,5 @@
+// What the approval page shows: the state of one approval session, as the CLI sends it to the page in the
+// browser (approve/src). The page renders it as it is, so every word the developer reads comes from here.
+// Types only, with no imports, so the page can import this file too.
+export {};
+//# sourceMappingURL=approval-view.js.map

package/dist/cli/approval-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval-view.js","sourceRoot":"","sources":["../../src/cli/approval-view.ts"],"names":[],"mappings":"AAAA,0GAA0G;AAC1G,0GAA0G;AAC1G,qEAAqE"}

package/dist/cli/approval.d.ts

@@ -0,0 +1,132 @@
+import { type StellarNetwork } from "@stellar-agent-services/protocol";
+import type { Transaction } from "@stellar/stellar-sdk";
+import type { ApprovalDetail, ApprovalState, ApprovalView } from "./approval-view.js";
+import { ApprovalError, type OwnerChain, type SendResult } from "./owner-chain.js";
+export { ApprovalError };
+/** What a command asks the developer to approve. */
+export interface ApprovalPlan {
+    /** Such as "provider-kit register". */
+    command: string;
+    title: string;
+    intro: string;
+    network: StellarNetwork;
+    /** The account to connect, when the command needs a particular one. */
+    account?: {
+        address: string;
+        label: string;
+        reason: string;
+    };
+    /** The steps the page lists before a wallet connects. */
+    outline: {
+        id: string;
+        title: string;
+    }[];
+    /** Checks the connected account and returns its steps, in order. Throws an ApprovalError when it can't go on. */
+    steps(address: string): Promise<ApprovalStep[]>;
+    /** What the page says once every step is done. */
+    result(): {
+        title: string;
+        message: string;
+        details: ApprovalDetail[];
+    };
+}
+export type ApprovalStep = 
+/** Something done without a signature, such as funding a new testnet account. Returns what happened. */
+{
+    kind: "auto";
+    id: string;
+    title: string;
+    run(): Promise<string>;
+}
+/** A transaction the wallet signs. build() runs when the step is due; done() says what it did. */
+ | {
+    kind: "sign";
+    id: string;
+    title: string;
+    build(): Promise<ProposedTransaction>;
+    done(sent: Extract<SendResult, {
+        status: "success";
+    }>): string | Promise<string>;
+};
+/** A transaction to sign, and what it does in plain words. */
+export interface ProposedTransaction {
+    transaction: Transaction;
+    summary: string;
+    details: ApprovalDetail[];
+}
+export type ApprovalOutcome = {
+    status: "done";
+    address: string;
+} | {
+    status: "cancelled";
+} | {
+    status: "expired";
+} | {
+    status: "failed";
+    reason: string;
+};
+/** A request the session can't take now, such as an approval for a step that isn't due. The page reloads the view. */
+export declare class ApprovalConflict extends Error {
+    name: string;
+}
+/** One command's approval: its steps, run in order as the developer connects a wallet and approves. */
+export declare class ApprovalSession {
+    #private;
+    readonly plan: ApprovalPlan;
+    readonly chain: OwnerChain;
+    readonly log: (line: string) => void;
+    readonly finished: Promise<ApprovalOutcome>;
+    constructor(plan: ApprovalPlan, chain: OwnerChain, log?: (line: string) => void);
+    get state(): ApprovalState;
+    /** Whether a request is under way, such as a check, a build or a transaction being sent. */
+    get busy(): boolean;
+    view(): ApprovalView;
+    /** The wallet connected `address`: checks it, then runs the steps up to the first transaction to approve. */
+    connect(address: string, wallet?: string): Promise<void>;
+    /** The wallet signed the transaction waiting for approval: checks it is that very transaction, sends it and moves on. */
+    submit(stepId: string, signedXdr: string): Promise<void>;
+    /** Builds the transaction waiting for approval again: after it expired, or after the network refused it. */
+    rebuild(stepId: string): Promise<void>;
+    /**
+     * Ends the session before it is done. While a request is under way, such as a transaction being sent, it is
+     * refused, or with `whenIdle` the session ends as soon as that request finishes.
+     */
+    cancel(whenIdle?: boolean): void;
+    /** Ends a session left idle. A session in the middle of something carries on. */
+    expire(): void;
+}
+/** What the terminal says when a session ends without finishing. */
+export declare function describeOutcome(outcome: Exclude<ApprovalOutcome, {
+    status: "done";
+}>): string;
+/** The built page: dist/approve, next to dist/cli. */
+export declare const APPROVAL_PAGE: import("url").URL;
+/** The page's port. A fixed one lets wallets remember that they connected to it before; a busy one falls back to any free port. */
+export declare const DEFAULT_APPROVAL_PORT = 8790;
+export interface ApprovalServer {
+    /** The link to open, with the token in its fragment. */
+    url: string;
+    port: number;
+    close(): Promise<void>;
+}
+export interface ApprovalServerOptions {
+    /** A port to use, which must be free. Without it: DEFAULT_APPROVAL_PORT, or any free port when that one is busy. */
+    port?: number;
+    /** The built page's directory. */
+    page?: URL;
+    /** How long the session may sit idle before it expires. */
+    idleMs?: number;
+}
+export declare function startApprovalServer(session: ApprovalSession, options?: ApprovalServerOptions): Promise<ApprovalServer>;
+/** Opens `url` in the default browser. Best effort: the terminal shows the link too. */
+export declare function openBrowser(url: string): void;
+export interface ApproveOptions {
+    port?: number;
+    /** false: print the link without opening a browser, as over SSH. */
+    open?: boolean;
+    page?: URL;
+    log?: (line: string) => void;
+}
+/** Opens the approval page for `plan` and waits until the developer finishes or cancels. */
+export declare function approveInBrowser(plan: ApprovalPlan, chain: OwnerChain, options?: ApproveOptions): Promise<ApprovalOutcome>;
+//# sourceMappingURL=approval.d.ts.map

package/dist/cli/approval.d.ts.map

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