@proxy-checkout/server-js 0.0.6-prx-94.51.1 → 0.0.6-prx-101.57.1

package/README.md

@@ -12,8 +12,8 @@ This package should expose the merchant-authenticated backend routes that exist
 | `proxy.sessions.createHandoff` | `POST /proxy_sessions/handoff` | Create a Proxy session and atomically mark it ready for hosted payer handoff. |
 | `proxy.sessions.retrieve` | `GET /proxy_sessions/:id/merchant` | Retrieve current merchant-owned session state after a webhook or before creating PSP objects. |
 | `proxy.sessions.cart.set` | `PUT /proxy_sessions/:id/cart` | Replace the current cart snapshot before payment orchestration. |
-| `proxy.sessions.payerHandoff` | `POST /proxy_sessions/:id/payer_handoff` | Record merchant handoff issuance before the payer loads checkout. |
-| `proxy.sessions.payerOpened` | `POST /proxy_sessions/:id/payer_opened` | Record checkout open and read the current merchant session/cart state. |
+| `proxy.sessions.payerHandoff` | `POST /proxy_sessions/:id/payer_handoff` | Low-level escape hatch. Most delegated checkout integrations should use `createHandoff`. |
+| `proxy.sessions.payerOpened` | `POST /proxy_sessions/:id/payer_opened` | Low-level escape hatch. Stripe integrations should usually let `@proxy-checkout/stripe-server-js` call this through `openCheckout`. |
 | `proxy.subscriptions.retrieve` | `GET /subscriptions/:id` | Retrieve current Proxy-linked subscription lifecycle state. |
 | `proxy.webhookEndpoints.list` | `GET /webhook_endpoints` | List outbound merchant webhook endpoints. |
 | `proxy.webhookEndpoints.create` | `POST /webhook_endpoints` | Create an outbound endpoint and receive its one-time signing secret. |
@@ -62,6 +62,14 @@ const endpoint = await proxy.webhookEndpoints.create({
 console.log(endpoint.signingSecret);
 ```
 
+For delegated checkout, prefer the high-level flow:
+
+1. Create buyer handoffs with `proxy.sessions.createHandoff(...)`.
+2. Let `@proxy-checkout/stripe-server-js` `openCheckout(...)` record payer-opened, create the merchant-owned Stripe object, inject required metadata, and record provider binding.
+3. Let `proxy.webhooks.handle(...)` verify signed Proxy webhooks, resolve current state, and acknowledge initial provisioning.
+
+Use `payerHandoff`, `payerOpened`, raw event construction, or manual provisioning acknowledgements only for custom integrations that cannot use the default helpers.
+
 Verify and parse outbound webhooks with the exact raw request body:
 
 ```ts

package/dist/cjs/sessions.js

@@ -89,11 +89,12 @@ class ProxySessionsResource {
         const session = toProxySessionHandoff(response);
         return {
             ...session,
-            handoffUrl: buildHandoffUrl({
-                payHost,
-                proxySessionId: session.id,
-                publishableKey,
-            }),
+            handoffUrl: session.handoffUrl ||
+                buildHandoffUrl({
+                    payHost,
+                    proxySessionId: session.id,
+                    publishableKey,
+                }),
         };
     }
     async retrieve(proxySessionId, options = {}) {
@@ -239,7 +240,11 @@ function toProxySessionHandoff(response) {
     const integrationMode = (0, response_validators_js_1.requireString)(body.integration_mode, "sessions.createHandoff.integrationMode");
     return {
         expiresAt: (0, response_validators_js_1.requireString)(body.expires_at, "sessions.createHandoff.expiresAt"),
-        handoffUrl: "",
+        handoffUrl: typeof body.handoff_url === "string"
+            ? body.handoff_url
+            : typeof body.handoffUrl === "string"
+                ? body.handoffUrl
+                : "",
         id: (0, response_validators_js_1.requireString)(body.id, "sessions.createHandoff.id"),
         integrationMode,
         status,

package/dist/cjs/version.d.cts

@@ -1,3 +1,3 @@
 export declare const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export declare const proxyCheckoutServerSdkVersion = "0.0.6-prx-94.51.1";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.6-prx-94.51.1";
+export declare const proxyCheckoutServerSdkVersion = "0.0.6-prx-101.57.1";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.6-prx-101.57.1";

package/dist/cjs/version.d.ts

@@ -1,3 +1,3 @@
 export declare const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export declare const proxyCheckoutServerSdkVersion = "0.0.6-prx-94.51.1";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.6-prx-94.51.1";
+export declare const proxyCheckoutServerSdkVersion = "0.0.6-prx-101.57.1";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.6-prx-101.57.1";

package/dist/cjs/version.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.proxyCheckoutServerSdkUserAgent = exports.proxyCheckoutServerSdkVersion = exports.proxyCheckoutServerSdkName = void 0;
 exports.proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-exports.proxyCheckoutServerSdkVersion = "0.0.6-prx-94.51.1";
+exports.proxyCheckoutServerSdkVersion = "0.0.6-prx-101.57.1";
 exports.proxyCheckoutServerSdkUserAgent = `${exports.proxyCheckoutServerSdkName}/${exports.proxyCheckoutServerSdkVersion}`;

package/dist/esm/sessions.js

@@ -86,11 +86,12 @@ export class ProxySessionsResource {
         const session = toProxySessionHandoff(response);
         return {
             ...session,
-            handoffUrl: buildHandoffUrl({
-                payHost,
-                proxySessionId: session.id,
-                publishableKey,
-            }),
+            handoffUrl: session.handoffUrl ||
+                buildHandoffUrl({
+                    payHost,
+                    proxySessionId: session.id,
+                    publishableKey,
+                }),
         };
     }
     async retrieve(proxySessionId, options = {}) {
@@ -234,7 +235,11 @@ function toProxySessionHandoff(response) {
     const integrationMode = requireString(body.integration_mode, "sessions.createHandoff.integrationMode");
     return {
         expiresAt: requireString(body.expires_at, "sessions.createHandoff.expiresAt"),
-        handoffUrl: "",
+        handoffUrl: typeof body.handoff_url === "string"
+            ? body.handoff_url
+            : typeof body.handoffUrl === "string"
+                ? body.handoffUrl
+                : "",
         id: requireString(body.id, "sessions.createHandoff.id"),
         integrationMode,
         status,

package/dist/esm/version.d.ts

@@ -1,3 +1,3 @@
 export declare const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export declare const proxyCheckoutServerSdkVersion = "0.0.6-prx-94.51.1";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.6-prx-94.51.1";
+export declare const proxyCheckoutServerSdkVersion = "0.0.6-prx-101.57.1";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.6-prx-101.57.1";

package/dist/esm/version.js

@@ -1,3 +1,3 @@
 export const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export const proxyCheckoutServerSdkVersion = "0.0.6-prx-94.51.1";
+export const proxyCheckoutServerSdkVersion = "0.0.6-prx-101.57.1";
 export const proxyCheckoutServerSdkUserAgent = `${proxyCheckoutServerSdkName}/${proxyCheckoutServerSdkVersion}`;

package/package.json

@@ -7,7 +7,7 @@
   "sideEffects": false,
   "type": "module",
   "types": "./dist/esm/index.d.ts",
-  "version": "0.0.6-prx-94.51.1",
+  "version": "0.0.6-prx-101.57.1",
   "devDependencies": {
     "@types/node": "^24.12.4",
     "@vitest/coverage-v8": "4.1.7",