@wix/himalaya-cli 0.1558.0 → 0.1559.0

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/_types/stdlib/wix-sdk/online-programs/src/index.d.ts

@@ -164,7 +164,7 @@ export declare function queryParticipants(programId: string, opts?: {
     limit?: number;
 }, readOptions?: WixCallOptions): Promise<WixQueryParticipantsResponse>;
 /** Participant lifecycle state. */
-export type WixParticipantState = "JOINED" | "PAYMENT_PENDING" | "APPROVAL_PENDING" | "COMPLETED" | "INVITED" | "REMOVED" | string;
+export type WixParticipantState = "JOINED" | "PAYMENT_PENDING" | "ENROLLMENT_PENDING" | "APPROVAL_PENDING" | "COMPLETED" | "INVITED" | "REMOVED" | string;
 export interface WixParticipantPaymentPending {
     /** The payable handle for the cashier rail, when the program charges. */
     purchaseFlowId?: string;
@@ -172,7 +172,7 @@ export interface WixParticipantPaymentPending {
     snapshotId?: string;
 }
 /**
- * The participant JoinProgram hands back — a DIFFERENT entity from the roster
+ * The compatibility result joinProgram returns — a DIFFERENT entity from the roster
  * `WixParticipant` above, which is why it gets its own name. This one describes the join
  * outcome (`state`, `paymentPendingOptions`); the roster one describes who the member is
  * and how far they have got (`member`, `progress`, `enrollmentStatus`).
@@ -195,7 +195,16 @@ export interface WixJoinedParticipant {
 export interface WixJoinProgramResponse {
     participant?: WixJoinedParticipant;
 }
-/** Join a program as the signed-in member. Branch on `participant.state`. */
-export declare function joinProgram(programId: string): Promise<WixJoinProgramResponse>;
-/** The cashier handle to settle, or "" when the join needs no payment. */
+/**
+ * Join as the signed-in member through Join Applications. Read the current
+ * application first so an existing application is resumed without another create.
+ * Approved paid applications prepare
+ * SINGLE_PAYMENT and return the Wix Payments order as paymentPendingOptions.orderId.
+ * mayPreparePayment rechecks the caller's checkout guard before creating that order.
+ * @scope member
+ */
+export declare function joinProgram(programId: string, options?: {
+    mayPreparePayment?: () => boolean;
+}): Promise<WixJoinProgramResponse>;
+/** The cashier handle to settle, or "" when no payable order is available. */
 export declare function payableIdOf(participant?: WixJoinedParticipant): string;

package/dist/authoring-runtime/node_modules/@wix/himalaya/dist/wix-online-programs.mjs

@@ -29,13 +29,41 @@ function queryParticipants(programId, opts, readOptions) {
   };
   return wixCall("POST", "/online-programs/v3/participants/query", { query, fields: ["PROGRESS"] }, readOptions);
 }
-function joinProgram(programId) {
-  if (!programId) throw new Error("joinProgram: programId is required");
-  return wixCall(
-    "POST",
-    `/online-programs/v3/participants/${encodeURIComponent(programId)}/join`,
-    {}
-  );
+function joinProgramError(code, message) {
+  return Object.assign(new Error(`joinProgram: ${message}`), { code });
+}
+var JOIN_APPLICATIONS = "/online-programs/participants/v3/join-applications";
+async function joinProgram(programId, options) {
+  if (!programId) throw joinProgramError("program_id_required", "programId is required");
+  let response;
+  let currentReadSucceeded = false;
+  try {
+    response = await wixCall("GET", `${JOIN_APPLICATIONS}/current/${encodeURIComponent(programId)}`);
+    currentReadSucceeded = true;
+  } catch {
+  }
+  if (!currentReadSucceeded) {
+    response = await wixCall("POST", JOIN_APPLICATIONS, { joinApplication: { programId } });
+  }
+  let application = response?.joinApplication;
+  if (!application?.id || application.programId !== programId) throw joinProgramError("invalid_join_application", "invalid join application");
+  if (application.status === "APPROVED" && ["PAYMENT_PENDING", "PAYMENT_FAILED", "PAYMENT_CANCELED"].includes(application.paymentStatus ?? "")) {
+    if (options?.mayPreparePayment && !options.mayPreparePayment()) throw joinProgramError("payment_preparation_withdrawn", "payment preparation withdrawn");
+    const prepared = await wixCall("POST", `${JOIN_APPLICATIONS}/${encodeURIComponent(application.id)}/prepare-payment`, { paymentType: "SINGLE_PAYMENT" });
+    if (prepared?.joinApplication?.id !== application.id || prepared.joinApplication.programId !== programId) throw joinProgramError("invalid_prepared_application", "invalid prepared application");
+    application = prepared.joinApplication;
+  }
+  const participant = { programId, memberId: application.memberId };
+  if (application.status === "APPROVAL_PENDING") return { participant: { ...participant, state: "APPROVAL_PENDING" } };
+  if (application.status !== "APPROVED") throw joinProgramError("join_application_not_approved", "application not approved");
+  if (application.paymentStatus === "PENDING_OWNER_APPROVAL") return { participant: { ...participant, state: "ENROLLMENT_PENDING" } };
+  if (["NO_PAYMENT_REQUIRED", "PAYMENT_SUCCESSFUL"].includes(application.paymentStatus ?? "")) {
+    return { participant: application.participantId ? { ...participant, id: application.participantId, state: "JOINED" } : { ...participant, state: "ENROLLMENT_PENDING" } };
+  }
+  if (application.paymentStatus === "PAYMENT_IN_PROGRESS" && application.paymentInfo?.paymentOrderId) {
+    return { participant: { ...participant, state: "PAYMENT_PENDING", paymentPendingOptions: { orderId: application.paymentInfo.paymentOrderId } } };
+  }
+  throw joinProgramError("join_application_not_ready", "enrollment or payment is not ready");
 }
 function payableIdOf(participant) {
   const pending = participant?.paymentPendingOptions;

package/guides/sdk-reference.json

@@ -23983,7 +23983,7 @@
         "name": "WixParticipantState",
         "kind": "type",
         "jsdoc": "/** Participant lifecycle state. */",
-        "decl": "export type WixParticipantState =\n  | \"JOINED\"\n  | \"PAYMENT_PENDING\"\n  | \"APPROVAL_PENDING\"\n  | \"COMPLETED\"\n  | \"INVITED\"\n  | \"REMOVED\"\n  | string;"
+        "decl": "export type WixParticipantState =\n  | \"JOINED\"\n  | \"PAYMENT_PENDING\"\n  | \"ENROLLMENT_PENDING\"\n  | \"APPROVAL_PENDING\"\n  | \"COMPLETED\"\n  | \"INVITED\"\n  | \"REMOVED\"\n  | string;"
       },
       {
         "name": "WixParticipantPaymentPending",
@@ -23994,7 +23994,7 @@
       {
         "name": "WixJoinedParticipant",
         "kind": "interface",
-        "jsdoc": "/**\n * The participant JoinProgram hands back — a DIFFERENT entity from the roster\n * `WixParticipant` above, which is why it gets its own name. This one describes the join\n * outcome (`state`, `paymentPendingOptions`); the roster one describes who the member is\n * and how far they have got (`member`, `progress`, `enrollmentStatus`).\n *\n * Both were spelled `WixParticipant` until #2289, so TypeScript MERGED the two declarations\n * instead of keeping them apart. That is wrong twice over: the merged type carries every\n * field of both, so it describes neither response — and the merge is itself an error,\n * because `id` was required in the roster shape and optional here (TS2687 + TS2717).\n */",
+        "jsdoc": "/**\n * The compatibility result joinProgram returns — a DIFFERENT entity from the roster\n * `WixParticipant` above, which is why it gets its own name. This one describes the join\n * outcome (`state`, `paymentPendingOptions`); the roster one describes who the member is\n * and how far they have got (`member`, `progress`, `enrollmentStatus`).\n *\n * Both were spelled `WixParticipant` until #2289, so TypeScript MERGED the two declarations\n * instead of keeping them apart. That is wrong twice over: the merged type carries every\n * field of both, so it describes neither response — and the merge is itself an error,\n * because `id` was required in the roster shape and optional here (TS2687 + TS2717).\n */",
         "decl": "export interface WixJoinedParticipant {\n  id?: string;\n  programId?: string;\n  memberId?: string;\n  state?: WixParticipantState;\n  paymentPendingOptions?: WixParticipantPaymentPending;\n  joinedOptions?: { joinedDate?: string };\n}"
       },
       {
@@ -24006,14 +24006,14 @@
       {
         "name": "joinProgram",
         "kind": "function",
-        "jsdoc": "/** Join a program as the signed-in member. Branch on `participant.state`. */",
-        "decl": "export function joinProgram(programId: string): Promise<WixJoinProgramResponse>;",
-        "http": "POST /online-programs/v3/participants/{…}/join"
+        "jsdoc": "/**\n * Join as the signed-in member through Join Applications. Read the current\n * application first so an existing application is resumed without another create.\n * Approved paid applications prepare\n * SINGLE_PAYMENT and return the Wix Payments order as paymentPendingOptions.orderId.\n * mayPreparePayment rechecks the caller's checkout guard before creating that order.\n * @scope member\n */",
+        "decl": "export async function joinProgram(programId: string, options?: { mayPreparePayment?: () => boolean }): Promise<WixJoinProgramResponse>;",
+        "scope": "member"
       },
       {
         "name": "payableIdOf",
         "kind": "function",
-        "jsdoc": "/** The cashier handle to settle, or \"\" when the join needs no payment. */",
+        "jsdoc": "/** The cashier handle to settle, or \"\" when no payable order is available. */",
         "decl": "export function payableIdOf(participant?: WixJoinedParticipant): string;"
       }
     ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1558.0",
+  "version": "0.1559.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -71,5 +71,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "3e25c3d6c9c9f3a1d3abe87df97e8a1f848ce1a712d321126ce42454"
+  "falconPackageHash": "10b9cfbdf8247c393305b2341b984702640668ff76c32fbc09ae2d8e"
 }

package/templates/branded-lite/tier5-src/himi-branded-lite-program/index.ts

@@ -9,7 +9,7 @@ import { withOnlineWrites } from "../_shared/online-actions.js";
 // error card.
 //
 // Phase 2d — enrolling is NATIVE. `joinProgram` covers all three program kinds in
-// one call and the outcome is read off `participant.state`, not assumed:
+// the Join Applications API; its compatibility result exposes only confirmed outcomes:
 // a free/open program comes back JOINED with nothing to pay, a paid one comes back
 // PAYMENT_PENDING and settles on the shared in-app pay rail, and a private one comes
 // back APPROVAL_PENDING (the owner approves; there is nothing to charge). Any failure
@@ -190,18 +190,26 @@ interface CommerceGuards {
 async function enrollmentMessage(name: string, guards: CommerceGuards): Promise<string> {
   const blocked = () => iapPriceCopy("program").purchaseUnavailable;
   if (!guards.mayStart()) return blocked();
+  let preparationWithdrawn = false;
   try {
-    const joined = await joinProgram(inputId());
+    const joined = await joinProgram(inputId(), { mayPreparePayment: () => {
+      if (!guards.mayContinue()) preparationWithdrawn = true;
+      return !preparationWithdrawn;
+    } });
     const participant = joined.participant;
     const programState = (participant?.state ?? "").toUpperCase();
     if (programState === "APPROVAL_PENDING") {
       return copyParam("program.approvalPendingMessage", "Request sent — the host will approve your place.");
     }
+    if (programState === "ENROLLMENT_PENDING") {
+      return copyParam("program.enrollmentPendingMessage", "Your enrollment is processing — check back shortly.");
+    }
     const payable = payableIdOf(participant);
-    if (!payable) {
-      // Free / open program (or one already settled) ⇒ nothing to charge.
+    if (programState === "JOINED") {
+      // Only a confirmed participant is enrolled; absent payment data is not success.
       return copyTemplate("program.joinedMessage", "You're enrolled in {name}.", { name });
     }
+    if (programState !== "PAYMENT_PENDING" || !payable) throw new Error("Program enrollment is not ready");
     const msid = await wixPlatformSession.signedInstanceStatus().then((s) => s.msid ?? "").catch(() => "");
     // Re-read before each step that commits money: a route that settles meanwhile wins.
     let withdrawn = false;
@@ -221,12 +229,8 @@ async function enrollmentMessage(name: string, guards: CommerceGuards): Promise<
       // which is precisely the dead-end the two-rail design exists to prevent
       // (and which the cart/plans/events flows each guard with a test).
       //
-      // There is no `programsCheckout` redirect intent. `ecomOrderPaymentRequest`
-      // is the only payment-request-shaped one, and a program's `purchaseFlowId`
-      // is a payment-request handle, so that is what we hand it. If that mapping
-      // is ever wrong the call throws, we degrade to the same site-directing
-      // message as before, and nothing regresses — but when it is right, a
-      // wallet-less site can actually sell the program IN-APP.
+      // Join Applications returns a Wix Payments order id; the payment-request
+      // redirect uses that same order handle on the hosted rail.
       cashierUrl: async () => {
         if (!stillAllowed()) return undefined;
         const redirect = await createRedirectSession({
@@ -237,10 +241,13 @@ async function enrollmentMessage(name: string, guards: CommerceGuards): Promise<
       },
     });
     if (withdrawn) return blocked();
-    if (pay.kind === "paid") return copyTemplate("program.joinedMessage", "You're enrolled in {name}.", { name });
+    if (pay.kind === "paid") return pay.pending
+      ? copyParam("program.paymentPendingMessage", "Payment is processing — enrollment will be confirmed after payment.")
+      : copyTemplate("program.joinedMessage", "You're enrolled in {name}.", { name });
     if (pay.kind === "handoff") return "";
     if (pay.kind === "cancelled") return copyParam("program.joinCancelledMessage", "Payment cancelled — you haven't enrolled.");
   } catch {
+    if (preparationWithdrawn) return blocked();
     // fall through to the site-directing message
   }
   return copyTemplate("program.joinOnSiteMessage", "Enrolment happens on the website — visit the site to join {name}.", { name });

package/templates/yoga-studio/tier5-src/himi-branded-lite-program/index.ts

@@ -9,7 +9,7 @@ import { withOnlineWrites } from "../_shared/online-actions.js";
 // error card.
 //
 // Phase 2d — enrolling is NATIVE. `joinProgram` covers all three program kinds in
-// one call and the outcome is read off `participant.state`, not assumed:
+// the Join Applications API; its compatibility result exposes only confirmed outcomes:
 // a free/open program comes back JOINED with nothing to pay, a paid one comes back
 // PAYMENT_PENDING and settles on the shared in-app pay rail, and a private one comes
 // back APPROVAL_PENDING (the owner approves; there is nothing to charge). Any failure
@@ -190,18 +190,26 @@ interface CommerceGuards {
 async function enrollmentMessage(name: string, guards: CommerceGuards): Promise<string> {
   const blocked = () => iapPriceCopy("program").purchaseUnavailable;
   if (!guards.mayStart()) return blocked();
+  let preparationWithdrawn = false;
   try {
-    const joined = await joinProgram(inputId());
+    const joined = await joinProgram(inputId(), { mayPreparePayment: () => {
+      if (!guards.mayContinue()) preparationWithdrawn = true;
+      return !preparationWithdrawn;
+    } });
     const participant = joined.participant;
     const programState = (participant?.state ?? "").toUpperCase();
     if (programState === "APPROVAL_PENDING") {
       return copyParam("program.approvalPendingMessage", "Request sent — the host will approve your place.");
     }
+    if (programState === "ENROLLMENT_PENDING") {
+      return copyParam("program.enrollmentPendingMessage", "Your enrollment is processing — check back shortly.");
+    }
     const payable = payableIdOf(participant);
-    if (!payable) {
-      // Free / open program (or one already settled) ⇒ nothing to charge.
+    if (programState === "JOINED") {
+      // Only a confirmed participant is enrolled; absent payment data is not success.
       return copyTemplate("program.joinedMessage", "You're enrolled in {name}.", { name });
     }
+    if (programState !== "PAYMENT_PENDING" || !payable) throw new Error("Program enrollment is not ready");
     const msid = await wixPlatformSession.signedInstanceStatus().then((s) => s.msid ?? "").catch(() => "");
     // Re-read before each step that commits money: a route that settles meanwhile wins.
     let withdrawn = false;
@@ -221,12 +229,8 @@ async function enrollmentMessage(name: string, guards: CommerceGuards): Promise<
       // which is precisely the dead-end the two-rail design exists to prevent
       // (and which the cart/plans/events flows each guard with a test).
       //
-      // There is no `programsCheckout` redirect intent. `ecomOrderPaymentRequest`
-      // is the only payment-request-shaped one, and a program's `purchaseFlowId`
-      // is a payment-request handle, so that is what we hand it. If that mapping
-      // is ever wrong the call throws, we degrade to the same site-directing
-      // message as before, and nothing regresses — but when it is right, a
-      // wallet-less site can actually sell the program IN-APP.
+      // Join Applications returns a Wix Payments order id; the payment-request
+      // redirect uses that same order handle on the hosted rail.
       cashierUrl: async () => {
         if (!stillAllowed()) return undefined;
         const redirect = await createRedirectSession({
@@ -237,10 +241,13 @@ async function enrollmentMessage(name: string, guards: CommerceGuards): Promise<
       },
     });
     if (withdrawn) return blocked();
-    if (pay.kind === "paid") return copyTemplate("program.joinedMessage", "You're enrolled in {name}.", { name });
+    if (pay.kind === "paid") return pay.pending
+      ? copyParam("program.paymentPendingMessage", "Payment is processing — enrollment will be confirmed after payment.")
+      : copyTemplate("program.joinedMessage", "You're enrolled in {name}.", { name });
     if (pay.kind === "handoff") return "";
     if (pay.kind === "cancelled") return copyParam("program.joinCancelledMessage", "Payment cancelled — you haven't enrolled.");
   } catch {
+    if (preparationWithdrawn) return blocked();
     // fall through to the site-directing message
   }
   return copyTemplate("program.joinOnSiteMessage", "Enrolment happens on the website — visit the site to join {name}.", { name });