@hsuite/smart-engines-cli 1.2.0 → 1.4.0

package/dist/commands/subscribe.d.ts

@@ -1,38 +1,113 @@
 /**
- * `hsuite subscribe` — Mint a subscription NFT against the validator's
- * `/api/v3/subscription/*` surface.
+ * `hsuite subscribe` — Onboard a smart-app the CANONICAL, MINT-FIRST way:
+ * create the smart-app's DKG ENTITY first, mint the builder subscription NFT
+ * ON THAT ENTITY's id, and land it on the dev wallet — so `1 smart-app =
+ * 1 DKG entity = 1 NFT`, ACTIVE from mint.
  *
- * Flow (per docs/superpowers/specs/2026-05-27-developer-subscription-gating.md §3.5):
- *   1. Read XRPL_ADDRESS + XRPL_SEED from env (written by `hsuite init`).
- *   2. POST /api/v3/subscription/request → server creates subscription doc.
- *      - `free_testnet`: server auto-activates + mints. CLI polls /status
- *         until NFT serial is set.
- *      - paid tier: server returns depositInstructions. CLI displays them,
- *         polls /status every 5s until status: 'PENDING_MINT' (deposit
- *         confirmed), then POSTs /mint to flip ACTIVE.
- *   3. Verify NFT serial lands on the wallet via GET /status.
- *   4. Write SUBSCRIPTION_APP_ID + SUBSCRIPTION_NFT_SERIAL to .env.
+ * ## Why this creates the entity (the mint-first re-architecture)
+ *
+ * `subscribe` used to mint the subscription NFT on a throwaway random
+ * `app-${uuid}` that was NEVER a DKG entity, while `hsuite deploy` separately
+ * minted a FRESH entity (+ a SECOND subscription) at `init` time. Paid id ≠
+ * deployed id → the deployed app stayed PENDING, redeploys forked, and two
+ * NFTs were minted. Now `subscribe` creates the durable DKG entity up front and
+ * uses its `entityId` as the subscription appId end-to-end; `deploy` reuses
+ * that same id (it no longer creates anything). Output:
+ * `SUBSCRIPTION_APP_ID == DEPLOYED_APP_ID == DKG entityId`, ACTIVE, ONE NFT.
+ *
+ * Full flow:
+ *   1. Read XRPL_ADDRESS + XRPL_SEED from env (written by `hsuite init`) and the
+ *      validator URL.
+ *   2. Web3-auth against the validator (challenge → sign → bearer). The
+ *      subscription + create routes are session-guarded. (Auth routes have NO
+ *      /api prefix.)
+ *   3. POST /api/v3/smart-apps (createApp) — run the per-entity DKG ceremony
+ *      to derive the canonical `entityId` AND create the (paid, pending-deposit)
+ *      subscription in the same in-process flow. The response carries
+ *      `{ appId: entityId, depositInstructions, subscriptionId }`. THIS replaces
+ *      the old random-id + standalone `subscription/request`. From here the
+ *      `entityId` is THE appId for everything downstream.
+ *   4. Ensure deposit instructions: the createApp response normally carries them.
+ *      If a node deferred deposit-account creation, fall back to the idempotent
+ *      POST /api/v3/subscription/request { appId: entityId, … } (same retry/503
+ *      semantics, returns the SAME subscription's deposit instructions — no
+ *      second subscription, no second deposit wallet).
+ *   5. Render the deposit instructions.
+ *   6. AUTO-PAY the deposit from the dev wallet over the XRPL testnet (HST
+ *      Payment with a SendMax covering the 0.25% transfer fee). `--no-autopay`
+ *      skips this and prints instructions for manual (XUMM) payment.
+ *   7. Poll GET /api/v3/subscription/status/:entityId until the deposit is
+ *      confirmed and ready to mint (status in { deposit_confirmed, pending_mint,
+ *      minting, active }; the real confirmed status is `deposit_confirmed`).
+ *   8. POST /api/v3/subscription/mint/:entityId — activates the subscription +
+ *      flips the SmartApp doc PENDING_SUBSCRIPTION → ACTIVE (via `activateApp`,
+ *      gated on the deposit-backed NFT mint) and kicks off the async NFT mint.
+ *   9. Poll /status until `subscriptionNftSerial` is set OR `chainNfts.xrpl.nftId`
+ *      is present (the NFT mints asynchronously via the mint subscriber).
+ *  10. Accept the brokered NFT sell offer so it lands on the dev wallet.
+ *  11. Verify account_nfts, then write SUBSCRIPTION_APP_ID + APP_ID +
+ *      SUBSCRIPTION_NFT_SERIAL (= entityId) to the env file.
  */
 import { Command } from 'commander';
 import { SubscriptionClient } from '../_lib/subscription-client';
+/**
+ * Minimal structural shape of the bits of the `xrpl` Client we use for the
+ * deposit payment + NFT offer acceptance. Lets unit tests inject a fake without
+ * a real websocket.
+ */
+export type XrplNftClientLike = {
+    connect(): Promise<unknown>;
+    disconnect(): Promise<unknown>;
+    request(req: Record<string, unknown>): Promise<{
+        result: any;
+    }>;
+    autofill(tx: Record<string, unknown>): Promise<Record<string, unknown>>;
+    submitAndWait(blob: string): Promise<{
+        result: {
+            meta?: any;
+        };
+    }>;
+};
 type SubscribeOpts = {
     env: string;
     gateway?: string;
     tier: string;
-    networks: string;
-    appName?: string;
+    /** Explicit appId. Defaults to SUBSCRIPTION_APP_ID env, then a random id. */
     appId?: string;
+    appName?: string;
+    /** XRPL account that issues the subscription NFT. Optional override for the
+     * sell-offer discovery (the /status response now exposes it). */
+    nftIssuer?: string;
+    /** Skip the auto-pay step — print instructions and exit (manual XUMM pay). */
+    noAutopay?: boolean;
     pollIntervalMs?: number;
     pollTimeoutMs?: number;
+    /**
+     * Max status polls while waiting for the NFT to mint (default 24 × pollIntervalMs
+     * ≈ 120s). The 2-of-3 issuer MPC mint + sell-offer creation take ~15-25s, so the
+     * default gives ample headroom. Exposed for tests (kept fast via `sleep`).
+     */
+    nftPollAttempts?: number;
+    /**
+     * Max NFTokenAcceptOffer retries while the issuer's sell offer becomes
+     * queryable on-ledger (default 10 × acceptRetryMs). Exposed for tests.
+     */
+    acceptAttempts?: number;
+    /** Delay between accept retries (default pollIntervalMs, then 5000). */
+    acceptRetryMs?: number;
     clientFactory?: (baseUrl: string) => SubscriptionClient;
     sleep?: (ms: number) => Promise<void>;
+    /** Builds an XRPL client for deposit pay + NFT accept. Defaults to real `xrpl`. */
+    xrplClientFactory?: (wss: string) => XrplNftClientLike;
+    /** Signs a prepared XRPL tx with the dev seed → tx_blob. Defaults to `xrpl`. */
+    walletSignFactory?: (seed: string) => (tx: Record<string, unknown>) => string;
 };
 /**
  * Pure orchestration body — exported for unit tests.
  *
- * Returns the appId + NFT serial (when minted) so callers can persist them.
- * Throws on every error path; the command-level action wraps this and
- * exits the process.
+ * Returns the appId + NFT serial (once minted + accepted) so callers can
+ * persist them. Throws on every hard-error path; the command-level action wraps
+ * this and exits the process.
  */
 export declare function runSubscribe(opts: SubscribeOpts): Promise<{
     appId: string;
@@ -40,6 +115,8 @@ export declare function runSubscribe(opts: SubscribeOpts): Promise<{
     nftSerial?: number | string;
     tier: string;
     status?: string;
+    depositPaid: boolean;
+    nftAccepted: boolean;
 }>;
 export declare const subscribeCommand: Command;
 export {};

package/dist/commands/subscribe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subscribe.d.ts","sourceRoot":"","sources":["../../src/commands/subscribe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKpC,OAAO,EACL,kBAAkB,EAInB,MAAM,6BAA6B,CAAC;AAGrC,KAAK,aAAa,GAAG;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,kBAAkB,CAAC;IACxD,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC,CAAC;AAQF;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC,CAkFD;AA0DD,eAAO,MAAM,gBAAgB,SA4CzB,CAAC"}
+{"version":3,"file":"subscribe.d.ts","sourceRoot":"","sources":["../../src/commands/subscribe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,EACL,kBAAkB,EAKnB,MAAM,6BAA6B,CAAC;AAarC;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5B,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/B,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,GAAG,CAAA;KAAE,CAAC,CAAC;IAChE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACxE,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE;YAAE,IAAI,CAAC,EAAE,GAAG,CAAA;SAAE,CAAA;KAAE,CAAC,CAAC;CAClE,CAAC;AAEF,KAAK,aAAa,GAAG;IACnB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;qEACiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,wEAAwE;IACxE,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,aAAa,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,kBAAkB,CAAC;IACxD,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,mFAAmF;IACnF,iBAAiB,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,iBAAiB,CAAC;IACvD,gFAAgF;IAChF,iBAAiB,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC;CAC/E,CAAC;AA0BF;;;;;;GAMG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAAC;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,OAAO,CAAC;IACrB,WAAW,EAAE,OAAO,CAAC;CACtB,CAAC,CAoKD;AA+TD,eAAO,MAAM,gBAAgB,SA4EzB,CAAC"}