@lucid-agents/pi-xgate 0.1.5 → 0.1.6

package/src/transport.ts

@@ -0,0 +1,94 @@
+import {
+  XgateError,
+  type Invocation,
+  type PurchaseResult,
+} from "@lucid-agents/xgate-client/types";
+/** Response metadata safe to show Pi's `onResponse` hook: never payment or status credentials. */
+export interface XgateResponseHead {
+  status: number;
+  headers: Record<string, string>;
+}
+/**
+ * Rail-neutral payment terms and status for display. Pi shows them; it never selects or
+ * configures a rail. Amounts are unsigned integer strings in the asset's smallest unit, and
+ * amounts of different assets are never combined.
+ */
+export interface XgatePayment {
+  /** CAIP-2 network, e.g. `eip155:8453`. */
+  network: string;
+  /** Payment scheme as the payee advertised it, e.g. `batch-settlement`, `exact`, `session`. */
+  scheme: string;
+  asset: string;
+  payTo?: string;
+  /** Rail shape: `per-request` or `session` today; other values may appear. */
+  rail?: string;
+  /** Most this invocation could be charged. */
+  authorizedAtomic: string;
+  /** Verified charge, once known. */
+  chargedAtomic?: string;
+  /** `settled`, `pending`, `amount_unknown`, `released`, ...; anything but `settled` is unverified. */
+  status: string;
+  /** Settlement transaction or payee commitment, when one exists. */
+  reference?: string;
+  /** Session-rail balance after this payment, when the host reports one. */
+  channel?: XgateChannelBalance;
+}
+export interface XgateChannelBalance {
+  depositingAtomic: string;
+  lockedAtomic: string;
+  chargedAtomic: string;
+  pendingAtomic: string;
+  refundableAtomic: string;
+}
+export interface XgatePurchaseResult extends PurchaseResult {
+  payment?: XgatePayment;
+}
+/**
+ * A purchase that ended without a verified result. `pending` is true when money may have moved
+ * and the outcome is unknown: the invocation must be reconciled, never retried.
+ */
+export class XgatePurchaseError extends XgateError {
+  readonly invocationId: string;
+  readonly pending: boolean;
+  readonly payment?: XgatePayment;
+  constructor(
+    code: string,
+    invocationId: string,
+    pending: boolean,
+    payment?: XgatePayment,
+  ) {
+    super(code);
+    this.name = "XgatePurchaseError";
+    this.message = pending
+      ? `Xgate: ${code}. The payment outcome is unknown; do not retry. Reconcile it before another purchase.`
+      : `Xgate: ${code}. Inspect the payment status before another purchase.`;
+    this.invocationId = invocationId;
+    this.pending = pending;
+    if (payment) this.payment = payment;
+  }
+}
+/**
+ * Moves one frozen Pi request to xgate and returns the verified result. The provider owns
+ * catalog qualification, codecs and the invocation ID; the transport owns payment.
+ *
+ * `purchase` sends at most one paid submission per `Invocation.id`, never retries a paid
+ * request, and never pays again for an ID it has seen: a repeated ID rejects. It resolves
+ * only with a verified result and rejects on every other outcome, preferably with an
+ * `XgatePurchaseError` stating whether the payment is pending. `BrokerClient` is the
+ * standalone implementation.
+ */
+export interface XgateTransport {
+  /** Current router catalog rows. Called before every paid invocation. */
+  models(signal?: AbortSignal): Promise<unknown[]>;
+  purchase(
+    invocation: Invocation,
+    signal?: AbortSignal,
+    onResponse?: (response: XgateResponseHead) => Promise<void>,
+  ): Promise<XgatePurchaseResult>;
+  /** Optional `/xgate status` and `/xgate budget` view. */
+  status?(signal?: AbortSignal): Promise<unknown>;
+  /** Optional `/xgate receipts` view. */
+  receipts?(signal?: AbortSignal): Promise<unknown>;
+  /** Optional `/xgate reconcile <invocation ID>`. Never resends the request. */
+  reconcile?(invocationId: string, signal?: AbortSignal): Promise<unknown>;
+}