@alphawebai/hs-prism 0.1.0-rc.33 → 0.1.0-rc.35

package/dist/src/alphaweb/manifest.d.ts

@@ -1,7 +1,7 @@
 export declare const ALPHAWEB_STRIPE_WEBHOOK_EVENTS: readonly ["charge.dispute.closed", "charge.dispute.created", "charge.dispute.funds_reinstated", "charge.dispute.funds_withdrawn", "charge.dispute.updated", "mandate.updated", "payment_intent.amount_capturable_updated", "payment_intent.canceled", "payment_intent.payment_failed", "payment_intent.processing", "payment_intent.requires_action", "payment_intent.succeeded", "payment_method.attached", "payment_method.automatically_updated", "payment_method.detached", "payment_method.updated", "refund.created", "refund.failed", "refund.updated", "setup_intent.canceled", "setup_intent.requires_action", "setup_intent.setup_failed", "setup_intent.succeeded"];
 export declare const ALPHAWEB_PAYPAL_WEBHOOK_EVENTS: readonly ["CHECKOUT.ORDER.APPROVED", "CHECKOUT.ORDER.COMPLETED", "CHECKOUT.ORDER.PROCESSED", "CHECKOUT.PAYMENT-APPROVAL.REVERSED", "CUSTOMER.DISPUTE.CREATED", "CUSTOMER.DISPUTE.RESOLVED", "CUSTOMER.DISPUTE.UPDATED", "PAYMENT.AUTHORIZATION.CREATED", "PAYMENT.AUTHORIZATION.VOIDED", "PAYMENT.CAPTURE.COMPLETED", "PAYMENT.CAPTURE.DECLINED", "PAYMENT.CAPTURE.PENDING", "PAYMENT.CAPTURE.REFUNDED", "PAYMENT.CAPTURE.REVERSED", "PAYMENT.REFUND.FAILED", "PAYMENT.REFUND.PENDING", "RISK.DISPUTE.CREATED", "VAULT.PAYMENT-TOKEN.CREATED", "VAULT.PAYMENT-TOKEN.DELETED", "VAULT.PAYMENT-TOKEN.DELETION-INITIATED"];
 export declare const ALPHAWEB_PRISM_COMPATIBILITY_MANIFEST: Readonly<{
-    readonly release: "0.1.0-rc.33";
+    readonly release: "0.1.0-rc.35";
     readonly upstreamCommit: "b07af7d9dac271de729548e74217ddcf895c602b";
     readonly medusaRange: ">=2.17.2 <2.18.0";
     readonly stripeApiVersion: "2026-06-24.dahlia";

package/dist/src/alphaweb/manifest.js

@@ -49,7 +49,7 @@ exports.ALPHAWEB_PAYPAL_WEBHOOK_EVENTS = Object.freeze([
     'VAULT.PAYMENT-TOKEN.DELETION-INITIATED',
 ]);
 exports.ALPHAWEB_PRISM_COMPATIBILITY_MANIFEST = Object.freeze({
-    release: '0.1.0-rc.33',
+    release: '0.1.0-rc.35',
     upstreamCommit: 'b07af7d9dac271de729548e74217ddcf895c602b',
     medusaRange: '>=2.17.2 <2.18.0',
     stripeApiVersion: '2026-06-24.dahlia',

package/dist/src/alphaweb/paypal-connector.d.ts

@@ -1,5 +1,5 @@
 import { types } from '../payments/generated/proto';
-import type { PrismAuthorizeApprovedPaymentInput, PrismCancelInput, PrismCaptureInput, PrismCreateWebhookEndpointInput, PrismDeleteWebhookEndpointInput, PrismDisputeResult, PrismEstablishReusableReferenceInput, PrismFindPaymentInput, PrismFindRefundInput, PrismMerchantOperation, PrismPayPalConnectorOptions, PrismPayPalConnectorV1, PrismPayPalRuntimeVerification, PrismPayPalRuntimeVerificationInput, PrismPaymentResult, PrismRefundInput, PrismRefundResult, PrismRetrieveDisputeInput, PrismRetrievePaymentInput, PrismRetrieveRefundInput, PrismRetrieveWebhookEndpointInput, PrismRetryPaymentInput, PrismReusableReferenceDerivation, PrismUpdateWebhookEndpointInput, PrismWebhookEndpoint, PrismWebhookEndpointCreated, PrismWebhookParseInput, PrismWebhookParseResult } from './types';
+import type { PrismAuthorizeApprovedPaymentInput, PrismCancelInput, PrismCaptureInput, PrismCreateWebhookEndpointInput, PrismDeleteWebhookEndpointInput, PrismDisputeResult, PrismEstablishReusableReferenceInput, PrismFindPaymentInput, PrismFindRefundInput, PrismMerchantOperation, PrismPayPalConnectorOptions, PrismPayPalConnectorV1, PrismPayPalOrderLifecycle, PrismPayPalRuntimeVerification, PrismPayPalRuntimeVerificationInput, PrismPaymentResult, PrismRefundInput, PrismRefundResult, PrismRetrieveDisputeInput, PrismRetrieveOrderLifecycleInput, PrismRetrievePaymentInput, PrismRetrieveRefundInput, PrismRetrieveWebhookEndpointInput, PrismRetryPaymentInput, PrismReusableReferenceDerivation, PrismUpdateWebhookEndpointInput, PrismWebhookEndpoint, PrismWebhookEndpointCreated, PrismWebhookParseInput, PrismWebhookParseResult } from './types';
 interface MerchantAuthenticationPort {
     createServerAuthenticationToken(input: types.IMerchantAuthenticationServiceCreateServerAuthenticationTokenRequest): Promise<types.MerchantAuthenticationServiceCreateServerAuthenticationTokenResponse>;
 }
@@ -38,6 +38,7 @@ export declare class PrismPayPalConnector implements PrismPayPalConnectorV1 {
     authorizeApprovedPayment(input: PrismAuthorizeApprovedPaymentInput): Promise<PrismPaymentResult>;
     repeatPayment(input: PrismMerchantOperation): Promise<PrismPaymentResult>;
     retryPayment(input: PrismRetryPaymentInput): Promise<PrismPaymentResult>;
+    retrieveOrderLifecycle(input: PrismRetrieveOrderLifecycleInput): Promise<PrismPayPalOrderLifecycle>;
     retrievePayment(input: PrismRetrievePaymentInput): Promise<PrismPaymentResult>;
     establishReusableReference(input: PrismEstablishReusableReferenceInput): Promise<PrismReusableReferenceDerivation>;
     findPaymentsByMerchantOperation(_input: PrismFindPaymentInput): Promise<PrismPaymentResult[]>;

package/dist/src/alphaweb/paypal-connector.js

@@ -99,6 +99,41 @@ function operationMetadata(input) {
 function futureUseRequested(input) {
     return Boolean(input.futureUse) || input.metadata.alphaweb_setup_future_usage === 'off_session';
 }
+const PAYPAL_BROWSER_CONTINUATION_MAX_URL_LENGTH = 2048;
+function browserContinuationUrl(value, fieldName) {
+    const normalized = typeof value === 'string' ? value.trim() : '';
+    if (normalized.length < 1 || normalized.length > PAYPAL_BROWSER_CONTINUATION_MAX_URL_LENGTH) {
+        throw validationError(`PayPal ${fieldName} is invalid.`, 'PRISM_PAYPAL_BROWSER_CONTINUATION');
+    }
+    let parsed;
+    try {
+        parsed = new URL(normalized);
+    }
+    catch {
+        throw validationError(`PayPal ${fieldName} is invalid.`, 'PRISM_PAYPAL_BROWSER_CONTINUATION');
+    }
+    if (parsed.protocol !== 'https:' ||
+        !parsed.hostname ||
+        parsed.username.length > 0 ||
+        parsed.password.length > 0 ||
+        parsed.hash.length > 0) {
+        throw validationError(`PayPal ${fieldName} is invalid.`, 'PRISM_PAYPAL_BROWSER_CONTINUATION');
+    }
+    return parsed;
+}
+function browserContinuation(input) {
+    if (!futureUseRequested(input))
+        return undefined;
+    if (!input.browserContinuation) {
+        throw validationError('PayPal future-use checkout requires trusted return and cancel URLs.', 'PRISM_PAYPAL_BROWSER_CONTINUATION');
+    }
+    const returnUrl = browserContinuationUrl(input.browserContinuation.returnUrl, 'return URL');
+    const cancelUrl = browserContinuationUrl(input.browserContinuation.cancelUrl, 'cancel URL');
+    if (returnUrl.origin !== cancelUrl.origin) {
+        throw validationError('PayPal return and cancel URLs must use the same storefront origin.', 'PRISM_PAYPAL_BROWSER_CONTINUATION');
+    }
+    return { returnUrl: returnUrl.toString(), cancelUrl: cancelUrl.toString() };
+}
 function futureUseMitCategoryFromIntent(futureUse) {
     if (futureUse?.recurringAgreement?.totalPayments !== null &&
         futureUse?.recurringAgreement?.totalPayments !== undefined) {
@@ -282,6 +317,34 @@ function paypalVaultStateFromOrder(payload, options, sourceConnectorPaymentId) {
     }
     return { status: 'absent' };
 }
+const PAYPAL_ORDER_LIFECYCLE_STATUSES = new Set([
+    'CREATED',
+    'SAVED',
+    'PAYER_ACTION_REQUIRED',
+    'APPROVED',
+    'VOIDED',
+    'COMPLETED',
+]);
+function orderLifecycleFrom(payload) {
+    const order = recordOf(payload);
+    const rawStatus = stringOf(order.status)?.toUpperCase();
+    const orderStatus = rawStatus && PAYPAL_ORDER_LIFECYCLE_STATUSES.has(rawStatus)
+        ? rawStatus
+        : 'UNKNOWN';
+    let hasAuthorization = false;
+    let hasCapture = false;
+    const purchaseUnits = Array.isArray(order.purchase_units) ? order.purchase_units : [];
+    for (const unit of purchaseUnits) {
+        const payments = recordOf(recordOf(unit).payments);
+        const authorizations = Array.isArray(payments.authorizations) ? payments.authorizations : [];
+        const captures = Array.isArray(payments.captures) ? payments.captures : [];
+        if (authorizations.some((entry) => stringOf(recordOf(entry).id)))
+            hasAuthorization = true;
+        if (captures.some((entry) => stringOf(recordOf(entry).id)))
+            hasCapture = true;
+    }
+    return { orderStatus, hasAuthorization, hasCapture };
+}
 function supportsPurposes(reference, purposes) {
     const requested = new Set(purposes);
     return !((requested.has('post_purchase') && !reference.capabilities.includes('post_purchase')) ||
@@ -760,9 +823,10 @@ class PrismPayPalConnector {
             throw validationError('Interactive payment input is invalid.', 'PRISM_INTERACTIVE_INPUT');
         }
         try {
-            const state = await this.connectorState();
             const setupFutureUsage = futureUseRequested(input);
             const recurringAgreement = recurringAgreementMessage(input);
+            const continuation = browserContinuation(input);
+            const state = await this.connectorState();
             const captureMethod = input.metadata.alphaweb_capture_method === 'manual'
                 ? proto_1.types.CaptureMethod.MANUAL
                 : proto_1.types.CaptureMethod.AUTOMATIC;
@@ -781,6 +845,7 @@ class PrismPayPalConnector {
                     ? futureUseMitCategory(input)
                     : proto_1.types.MitCategory.MIT_CATEGORY_UNSPECIFIED,
                 ...(recurringAgreement ? { recurringAgreement } : {}),
+                ...(continuation ?? {}),
             });
             const orderId = stringOf(order.connectorOrderId);
             if (!orderId) {
@@ -905,6 +970,16 @@ class PrismPayPalConnector {
         this.assertOperation(input);
         return this.repeatPayment(input);
     }
+    async retrieveOrderLifecycle(input) {
+        assertIdentifier(input.connectorPaymentId, 'connectorPaymentId');
+        try {
+            const payload = await this.paypalRequest('GET', `/v2/checkout/orders/${encodeURIComponent(input.connectorPaymentId)}`);
+            return orderLifecycleFrom(payload);
+        }
+        catch (error) {
+            throw (0, error_1.normalizePrismError)(error);
+        }
+    }
     async retrievePayment(input) {
         assertIdentifier(input.operationId, 'operationId');
         assertIdentifier(input.connectorPaymentId, 'connectorPaymentId');

package/dist/src/alphaweb/types.d.ts

@@ -26,6 +26,10 @@ export interface PrismFutureUseIntent {
     purposes: [PrismFutureUsePurpose, ...PrismFutureUsePurpose[]];
     recurringAgreement?: PrismRecurringAgreement;
 }
+export interface PrismBrowserContinuation {
+    returnUrl: string;
+    cancelUrl: string;
+}
 export interface PrismReusablePaymentReference {
     version: 1;
     connector: PrismConnectorId;
@@ -72,6 +76,7 @@ export interface PrismMerchantOperation {
     customerReference?: string;
     reusableReference?: PrismReusablePaymentReference;
     futureUse?: PrismFutureUseIntent;
+    browserContinuation?: PrismBrowserContinuation;
     methodSelection: {
         kind: 'interactive_dynamic';
         paymentMethodConfigurationId?: string;
@@ -320,8 +325,18 @@ export interface PrismConnectorV1 {
     retrieveWebhookEndpoint(input: PrismRetrieveWebhookEndpointInput): Promise<PrismWebhookEndpoint>;
 }
 export type PrismStripeConnectorV1 = PrismConnectorV1;
+export type PrismPayPalOrderLifecycleStatus = 'CREATED' | 'SAVED' | 'PAYER_ACTION_REQUIRED' | 'APPROVED' | 'VOIDED' | 'COMPLETED' | 'UNKNOWN';
+export interface PrismPayPalOrderLifecycle {
+    orderStatus: PrismPayPalOrderLifecycleStatus;
+    hasAuthorization: boolean;
+    hasCapture: boolean;
+}
+export interface PrismRetrieveOrderLifecycleInput {
+    connectorPaymentId: string;
+}
 export interface PrismPayPalConnectorV1 extends PrismConnectorV1 {
     authorizeApprovedPayment(input: PrismAuthorizeApprovedPaymentInput): Promise<PrismPaymentResult>;
+    retrieveOrderLifecycle?(input: PrismRetrieveOrderLifecycleInput): Promise<PrismPayPalOrderLifecycle>;
 }
 export interface PrismStripeConnectorOptions {
     environment: PrismEnvironment;

package/dist/src/payments/generated/proto.d.ts

@@ -15152,6 +15152,15 @@ export namespace types {
          * details in its provider-owned buyer approval surface.
          */
         recurringAgreement?: (types.IRecurringAgreement|null);
+
+        /**
+         * Provider-owned buyer continuation URLs for approval flows. Connectors that
+         * require future-use approval must fail closed when either URL is absent.
+         */
+        returnUrl?: (string|null);
+
+        /** PaymentServiceCreateOrderRequest cancelUrl */
+        cancelUrl?: (string|null);
     }
 
     /** Request message for creating an order */
@@ -15212,6 +15221,15 @@ export namespace types {
          */
         public recurringAgreement?: (types.IRecurringAgreement|null);
 
+        /**
+         * Provider-owned buyer continuation URLs for approval flows. Connectors that
+         * require future-use approval must fail closed when either URL is absent.
+         */
+        public returnUrl?: (string|null);
+
+        /** PaymentServiceCreateOrderRequest cancelUrl. */
+        public cancelUrl?: (string|null);
+
         /**
          * Creates a new PaymentServiceCreateOrderRequest instance using the specified properties.
          * @param [properties] Properties to set

package/dist/src/payments/generated/proto.js

@@ -47737,6 +47737,9 @@ $root.types = (function() {
          * recurring. Connectors that don't require this distinction may ignore it.
          * @property {types.IRecurringAgreement|null} [recurringAgreement] Required for recurring agreements when a connector must present cadence
          * details in its provider-owned buyer approval surface.
+         * @property {string|null} [returnUrl] Provider-owned buyer continuation URLs for approval flows. Connectors that
+         * require future-use approval must fail closed when either URL is absent.
+         * @property {string|null} [cancelUrl] PaymentServiceCreateOrderRequest cancelUrl
          */
 
         /**
@@ -47855,6 +47858,23 @@ $root.types = (function() {
          */
         PaymentServiceCreateOrderRequest.prototype.recurringAgreement = null;
 
+        /**
+         * Provider-owned buyer continuation URLs for approval flows. Connectors that
+         * require future-use approval must fail closed when either URL is absent.
+         * @member {string|null|undefined} returnUrl
+         * @memberof types.PaymentServiceCreateOrderRequest
+         * @instance
+         */
+        PaymentServiceCreateOrderRequest.prototype.returnUrl = null;
+
+        /**
+         * PaymentServiceCreateOrderRequest cancelUrl.
+         * @member {string|null|undefined} cancelUrl
+         * @memberof types.PaymentServiceCreateOrderRequest
+         * @instance
+         */
+        PaymentServiceCreateOrderRequest.prototype.cancelUrl = null;
+
         // OneOf field names bound to virtual getters and setters
         var $oneOfFields;
 
@@ -47924,6 +47944,18 @@ $root.types = (function() {
             set: $util.oneOfSetter($oneOfFields)
         });
 
+        // Virtual OneOf for proto3 optional field
+        Object.defineProperty(PaymentServiceCreateOrderRequest.prototype, "_returnUrl", {
+            get: $util.oneOfGetter($oneOfFields = ["returnUrl"]),
+            set: $util.oneOfSetter($oneOfFields)
+        });
+
+        // Virtual OneOf for proto3 optional field
+        Object.defineProperty(PaymentServiceCreateOrderRequest.prototype, "_cancelUrl", {
+            get: $util.oneOfGetter($oneOfFields = ["cancelUrl"]),
+            set: $util.oneOfSetter($oneOfFields)
+        });
+
         /**
          * Creates a new PaymentServiceCreateOrderRequest instance using the specified properties.
          * @function create
@@ -47976,6 +48008,10 @@ $root.types = (function() {
                 writer.uint32(/* id 11, wireType 0 =*/88).int32(message.mitCategory);
             if (message.recurringAgreement != null && Object.hasOwnProperty.call(message, "recurringAgreement"))
                 $root.types.RecurringAgreement.encode(message.recurringAgreement, writer.uint32(/* id 12, wireType 2 =*/98).fork(), q + 1).ldelim();
+            if (message.returnUrl != null && Object.hasOwnProperty.call(message, "returnUrl"))
+                writer.uint32(/* id 13, wireType 2 =*/106).string(message.returnUrl);
+            if (message.cancelUrl != null && Object.hasOwnProperty.call(message, "cancelUrl"))
+                writer.uint32(/* id 14, wireType 2 =*/114).string(message.cancelUrl);
             return writer;
         };
 
@@ -48051,6 +48087,14 @@ $root.types = (function() {
                         message.recurringAgreement = $root.types.RecurringAgreement.decode(reader, reader.uint32(), undefined, long + 1);
                         break;
                     }
+                case 13: {
+                        message.returnUrl = reader.string();
+                        break;
+                    }
+                case 14: {
+                        message.cancelUrl = reader.string();
+                        break;
+                    }
                 default:
                     reader.skipType(tag & 7, long);
                     break;
@@ -48288,6 +48332,16 @@ $root.types = (function() {
                         return "recurringAgreement." + error;
                 }
             }
+            if (message.returnUrl != null && Object.hasOwnProperty.call(message, "returnUrl")) {
+                properties._returnUrl = 1;
+                if (!$util.isString(message.returnUrl))
+                    return "returnUrl: string expected";
+            }
+            if (message.cancelUrl != null && Object.hasOwnProperty.call(message, "cancelUrl")) {
+                properties._cancelUrl = 1;
+                if (!$util.isString(message.cancelUrl))
+                    return "cancelUrl: string expected";
+            }
             return null;
         };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alphawebai/hs-prism",
-  "version": "0.1.0-rc.33",
+  "version": "0.1.0-rc.35",
   "description": "Hyperswitch Payments SDK — Node.js client for connector integrations via UniFFI FFI",
   "main": "dist/src/index.js",
   "exports": {