@alphawebai/hs-prism 0.1.0-rc.39 → 0.1.0-rc.41

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

@@ -3,4 +3,5 @@ export type { AlphaWebPrismCompatibilityManifest } from './manifest';
 export { PrismOperationError, normalizePrismError } from './error';
 export { assertSafeProviderMoney, fromProviderMinorAmount, getCurrencyRule, toProviderMinorAmount, } from './money';
 export type { CurrencyRule } from './money';
+export { paypalQuotesMatch } from './paypal-approved-order';
 export type * from './types';

package/dist/src/alphaweb/contracts.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toProviderMinorAmount = exports.getCurrencyRule = exports.fromProviderMinorAmount = exports.assertSafeProviderMoney = exports.normalizePrismError = exports.PrismOperationError = exports.ALPHAWEB_PRISM_COMPATIBILITY_MANIFEST = void 0;
+exports.paypalQuotesMatch = exports.toProviderMinorAmount = exports.getCurrencyRule = exports.fromProviderMinorAmount = exports.assertSafeProviderMoney = exports.normalizePrismError = exports.PrismOperationError = exports.ALPHAWEB_PRISM_COMPATIBILITY_MANIFEST = void 0;
 var manifest_1 = require("./manifest");
 Object.defineProperty(exports, "ALPHAWEB_PRISM_COMPATIBILITY_MANIFEST", { enumerable: true, get: function () { return manifest_1.ALPHAWEB_PRISM_COMPATIBILITY_MANIFEST; } });
 var error_1 = require("./error");
@@ -11,4 +11,6 @@ Object.defineProperty(exports, "assertSafeProviderMoney", { enumerable: true, ge
 Object.defineProperty(exports, "fromProviderMinorAmount", { enumerable: true, get: function () { return money_1.fromProviderMinorAmount; } });
 Object.defineProperty(exports, "getCurrencyRule", { enumerable: true, get: function () { return money_1.getCurrencyRule; } });
 Object.defineProperty(exports, "toProviderMinorAmount", { enumerable: true, get: function () { return money_1.toProviderMinorAmount; } });
+var paypal_approved_order_1 = require("./paypal-approved-order");
+Object.defineProperty(exports, "paypalQuotesMatch", { enumerable: true, get: function () { return paypal_approved_order_1.paypalQuotesMatch; } });
 //# sourceMappingURL=contracts.js.map

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

@@ -2,6 +2,9 @@ export interface PrismOperationErrorShape {
     category: 'configuration' | 'authentication' | 'validation' | 'customer_action' | 'declined' | 'rate_limited' | 'network' | 'provider_server' | 'conflict' | 'unknown';
     providerCode?: string;
     providerRequestId?: string;
+    providerHttpStatus?: number;
+    /** Provider issue identifiers only; never descriptions, field values, or raw responses. */
+    providerIssueCodes?: readonly string[];
     retryable: boolean;
     outcome: 'definitely_not_applied' | 'applied' | 'ambiguous';
     safeMessage: string;

package/dist/src/alphaweb/error.js

@@ -101,6 +101,9 @@ function normalizePrismError(error) {
         category,
         ...(code ? { providerCode: code } : {}),
         ...(requestId ? { providerRequestId: requestId } : {}),
+        ...(Number.isInteger(status) && status >= 100 && status <= 599
+            ? { providerHttpStatus: status }
+            : {}),
         retryable,
         outcome,
         safeMessage,

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.39";
+    readonly release: "0.1.0-rc.41";
     readonly upstreamCommit: "b07af7d9dac271de729548e74217ddcf895c602b";
     readonly medusaRange: ">=2.17.2 <2.18.0";
     readonly stripeApiVersion: "2026-06-24.dahlia";
@@ -34,6 +34,7 @@ export declare const ALPHAWEB_PRISM_COMPATIBILITY_MANIFEST: Readonly<{
         };
         readonly paypal: {
             readonly browserSession: "paypal_checkout";
+            readonly approvedOrderCheckout: "v1";
             readonly oneTimePayment: true;
             readonly futureUse: true;
             readonly repeatPayment: true;

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.39',
+    release: '0.1.0-rc.41',
     upstreamCommit: 'b07af7d9dac271de729548e74217ddcf895c602b',
     medusaRange: '>=2.17.2 <2.18.0',
     stripeApiVersion: '2026-06-24.dahlia',
@@ -82,6 +82,7 @@ exports.ALPHAWEB_PRISM_COMPATIBILITY_MANIFEST = Object.freeze({
         },
         paypal: {
             browserSession: 'paypal_checkout',
+            approvedOrderCheckout: 'v1',
             oneTimePayment: true,
             futureUse: true,
             repeatPayment: true,

package/dist/src/alphaweb/paypal-approved-order.d.ts

@@ -0,0 +1,49 @@
+import { PrismOperationError } from './error';
+import type { PrismPayPalApprovedOrder, PrismPayPalConnectorOptions, PrismPayPalOrderOwner, PrismPayPalOrderQuote } from './types';
+export declare function approvedOrderError(code: string, outcome?: 'ambiguous' | 'definitely_not_applied'): PrismOperationError;
+export declare function paypalQuotePayload(quote: PrismPayPalOrderQuote): {
+    items?: {
+        billing_plan?: {
+            name: string;
+            billing_cycles: {
+                tenure_type: string;
+                pricing_scheme: {
+                    price: {
+                        currency_code: string;
+                        value: string;
+                    };
+                    pricing_model: string;
+                };
+                frequency: {
+                    interval_unit: string;
+                    interval_count: number;
+                };
+                total_cycles: number;
+                sequence: number;
+            }[];
+        } | undefined;
+        tax?: {
+            currency_code: string;
+            value: string;
+        } | undefined;
+        category?: "DIGITAL_GOODS" | "PHYSICAL_GOODS" | "DONATION" | undefined;
+        sku?: string | undefined;
+        name: string;
+        quantity: string;
+        unit_amount: {
+            currency_code: string;
+            value: string;
+        };
+    }[] | undefined;
+    amount: {
+        breakdown?: Record<string, {
+            currency_code: string;
+            value: string;
+        }> | undefined;
+        currency_code: string;
+        value: string;
+    };
+};
+export declare function paypalQuotesMatch(left: PrismPayPalOrderQuote, right: PrismPayPalOrderQuote): boolean;
+export declare function assertRecurringDisclosurePreserved(previous: PrismPayPalOrderQuote, next: PrismPayPalOrderQuote): void;
+export declare function readApprovedOrder(payload: unknown, owner: PrismPayPalOrderOwner, options: Readonly<PrismPayPalConnectorOptions>): PrismPayPalApprovedOrder;

package/dist/src/alphaweb/paypal-approved-order.js

@@ -0,0 +1,326 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.approvedOrderError = approvedOrderError;
+exports.paypalQuotePayload = paypalQuotePayload;
+exports.paypalQuotesMatch = paypalQuotesMatch;
+exports.assertRecurringDisclosurePreserved = assertRecurringDisclosurePreserved;
+exports.readApprovedOrder = readApprovedOrder;
+const node_util_1 = require("node:util");
+const error_1 = require("./error");
+const money_1 = require("./money");
+const breakdownFields = {
+    itemTotalMinor: 'item_total',
+    taxTotalMinor: 'tax_total',
+    shippingMinor: 'shipping',
+    handlingMinor: 'handling',
+    insuranceMinor: 'insurance',
+    shippingDiscountMinor: 'shipping_discount',
+    discountMinor: 'discount',
+};
+function record(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+function text(value) {
+    return typeof value === 'string' ? value : '';
+}
+function approvedOrderError(code, outcome = 'ambiguous') {
+    return new error_1.PrismOperationError({
+        category: 'conflict',
+        providerCode: code,
+        retryable: false,
+        outcome,
+        safeMessage: 'The PayPal order must be verified before payment can continue.',
+    });
+}
+function moneyFrom(value, currency) {
+    const amount = record(value);
+    const code = text(amount.currency_code).toLowerCase();
+    if (!code || (currency && currency !== code) || typeof amount.value !== 'string') {
+        throw approvedOrderError('PRISM_PAYPAL_ORDER_MONEY');
+    }
+    return {
+        currency: code,
+        amountMinor: (0, money_1.toProviderMinorAmount)({ medusaAmount: amount.value, currency: code }).toString(),
+    };
+}
+function providerMoney(amountMinor, currency) {
+    return {
+        currency_code: currency.toUpperCase(),
+        value: (0, money_1.fromProviderMinorAmount)({ amountMinor, currency }),
+    };
+}
+function minor(value, currency) {
+    (0, money_1.fromProviderMinorAmount)({ amountMinor: value, currency });
+    return BigInt(value);
+}
+function recurringPlan(agreement, currency) {
+    const limits = { day: 365, week: 52, month: 12, year: 1 };
+    const money = (0, money_1.assertSafeProviderMoney)(agreement.recurringMoney);
+    if (money.currency !== currency ||
+        !agreement.planName.trim() ||
+        agreement.planName.length > 127 ||
+        !Number.isSafeInteger(agreement.intervalCount) ||
+        agreement.intervalCount < 1 ||
+        !(agreement.intervalUnit in limits) ||
+        agreement.intervalCount > limits[agreement.intervalUnit] ||
+        (agreement.totalPayments !== null &&
+            (!Number.isSafeInteger(agreement.totalPayments) ||
+                agreement.totalPayments < 2 ||
+                agreement.totalPayments > 999))) {
+        throw approvedOrderError('PRISM_PAYPAL_RECURRING_AGREEMENT', 'definitely_not_applied');
+    }
+    return {
+        name: agreement.planName,
+        billing_cycles: [
+            {
+                tenure_type: 'REGULAR',
+                pricing_scheme: {
+                    price: providerMoney(agreement.recurringMoney.amountMinor, currency),
+                    pricing_model: 'FIXED',
+                },
+                frequency: {
+                    interval_unit: agreement.intervalUnit.toUpperCase(),
+                    interval_count: agreement.intervalCount,
+                },
+                total_cycles: agreement.totalPayments ?? 0,
+                sequence: 1,
+            },
+        ],
+    };
+}
+function recurringFrom(value, currency) {
+    const plan = record(value);
+    const cycles = Array.isArray(plan.billing_cycles) ? plan.billing_cycles : [];
+    const cycle = record(cycles[0]);
+    const frequency = record(cycle.frequency);
+    const pricing = record(cycle.pricing_scheme);
+    const unit = text(frequency.interval_unit).toLowerCase();
+    if (cycles.length !== 1 ||
+        cycle.tenure_type !== 'REGULAR' ||
+        cycle.sequence !== 1 ||
+        pricing.pricing_model !== 'FIXED' ||
+        (unit !== 'day' && unit !== 'week' && unit !== 'month' && unit !== 'year')) {
+        throw approvedOrderError('PRISM_PAYPAL_RECURRING_AGREEMENT');
+    }
+    const agreement = {
+        planName: text(plan.name),
+        intervalUnit: unit,
+        intervalCount: Number(frequency.interval_count),
+        totalPayments: cycle.total_cycles === 0 ? null : Number(cycle.total_cycles),
+        recurringMoney: moneyFrom(pricing.price, currency),
+    };
+    recurringPlan(agreement, currency);
+    return agreement;
+}
+function buildQuotePayload(quote) {
+    const currency = (0, money_1.assertSafeProviderMoney)(quote.money).currency;
+    const breakdown = {};
+    let total = 0n;
+    for (const [key, field] of Object.entries(breakdownFields)) {
+        const value = quote.breakdown?.[key];
+        if (value === undefined)
+            continue;
+        const amount = minor(value, currency);
+        total += field === 'discount' || field === 'shipping_discount' ? -amount : amount;
+        breakdown[field] = providerMoney(value, currency);
+    }
+    if (quote.breakdown && total !== BigInt(quote.money.amountMinor)) {
+        throw approvedOrderError('PRISM_PAYPAL_QUOTE_TOTAL', 'definitely_not_applied');
+    }
+    let itemTotal = 0n;
+    let taxTotal = 0n;
+    const items = quote.items?.map((item) => {
+        if (!item.name.trim() ||
+            item.name.length > 127 ||
+            (item.sku !== undefined && (!item.sku || item.sku.length > 127)) ||
+            (item.category !== undefined &&
+                !['DIGITAL_GOODS', 'PHYSICAL_GOODS', 'DONATION'].includes(item.category)) ||
+            !Number.isSafeInteger(item.quantity) ||
+            item.quantity < 1) {
+            throw approvedOrderError('PRISM_PAYPAL_QUOTE_ITEM', 'definitely_not_applied');
+        }
+        itemTotal += minor(item.unitAmountMinor, currency) * BigInt(item.quantity);
+        taxTotal += minor(item.taxMinor ?? '0', currency) * BigInt(item.quantity);
+        return {
+            name: item.name,
+            quantity: String(item.quantity),
+            unit_amount: providerMoney(item.unitAmountMinor, currency),
+            ...(item.sku ? { sku: item.sku } : {}),
+            ...(item.category ? { category: item.category } : {}),
+            ...(item.taxMinor === undefined ? {} : { tax: providerMoney(item.taxMinor, currency) }),
+            ...(item.recurringAgreement
+                ? { billing_plan: recurringPlan(item.recurringAgreement, currency) }
+                : {}),
+        };
+    });
+    if (items &&
+        (!items.length ||
+            quote.breakdown?.itemTotalMinor === undefined ||
+            itemTotal !== BigInt(quote.breakdown.itemTotalMinor) ||
+            (quote.items?.some((item) => item.taxMinor !== undefined) &&
+                (quote.breakdown.taxTotalMinor === undefined ||
+                    taxTotal !== BigInt(quote.breakdown.taxTotalMinor))))) {
+        throw approvedOrderError('PRISM_PAYPAL_QUOTE_ITEMS_TOTAL', 'definitely_not_applied');
+    }
+    return {
+        amount: {
+            ...providerMoney(quote.money.amountMinor, currency),
+            ...(quote.breakdown ? { breakdown } : {}),
+        },
+        ...(items ? { items } : {}),
+    };
+}
+function paypalQuotePayload(quote) {
+    try {
+        return buildQuotePayload(quote);
+    }
+    catch (error) {
+        if (error instanceof error_1.PrismOperationError)
+            throw error;
+        throw approvedOrderError('PRISM_PAYPAL_QUOTE_INVALID', 'definitely_not_applied');
+    }
+}
+function paypalQuotesMatch(left, right) {
+    return (0, node_util_1.isDeepStrictEqual)(paypalQuotePayload(left), paypalQuotePayload(right));
+}
+function assertRecurringDisclosurePreserved(previous, next) {
+    const agreements = (quote) => quote.items
+        ?.filter((item) => item.recurringAgreement)
+        .map((item) => ({ quantity: item.quantity, agreement: item.recurringAgreement })) ?? [];
+    if (!(0, node_util_1.isDeepStrictEqual)(agreements(previous), agreements(next))) {
+        throw approvedOrderError('PRISM_PAYPAL_RECURRING_AGREEMENT_CHANGED', 'definitely_not_applied');
+    }
+}
+function readApprovedOrder(payload, owner, options) {
+    const order = record(payload);
+    const units = Array.isArray(order.purchase_units) ? order.purchase_units : [];
+    const unit = record(units[0]);
+    const payee = record(unit.payee);
+    if (owner.credentialBindingId !== options.credentialBindingId ||
+        owner.providerAccountId !== options.providerAccountId ||
+        owner.livemode !== (options.environment === 'live') ||
+        order.id !== owner.connectorPaymentId ||
+        order.intent !== 'CAPTURE' ||
+        units.length !== 1 ||
+        unit.reference_id !== owner.rootOperationId ||
+        unit.invoice_id !== owner.rootOperationId ||
+        (owner.expectedCustomId !== undefined && unit.custom_id !== owner.expectedCustomId) ||
+        (options.payerId !== undefined && payee.merchant_id !== options.payerId)) {
+        throw approvedOrderError('PRISM_PAYPAL_ORDER_OWNER');
+    }
+    const money = moneyFrom(unit.amount);
+    const suppliedBreakdown = record(unit.amount).breakdown;
+    const rawBreakdown = record(suppliedBreakdown);
+    if ((suppliedBreakdown !== undefined &&
+        (suppliedBreakdown === null ||
+            typeof suppliedBreakdown !== 'object' ||
+            Array.isArray(suppliedBreakdown))) ||
+        Object.keys(rawBreakdown).some((field) => !Object.values(breakdownFields).some((known) => known === field)) ||
+        (unit.items !== undefined && !Array.isArray(unit.items))) {
+        throw approvedOrderError('PRISM_PAYPAL_ORDER_RESPONSE');
+    }
+    const breakdown = {};
+    for (const [key, field] of Object.entries(breakdownFields)) {
+        if (rawBreakdown[field] !== undefined)
+            breakdown[key] = moneyFrom(rawBreakdown[field], money.currency).amountMinor;
+    }
+    const items = Array.isArray(unit.items)
+        ? unit.items.map((value) => {
+            const item = record(value);
+            return {
+                name: text(item.name),
+                quantity: Number(item.quantity),
+                unitAmountMinor: moneyFrom(item.unit_amount, money.currency).amountMinor,
+                ...(item.sku === undefined ? {} : { sku: text(item.sku) }),
+                ...(item.category === undefined
+                    ? {}
+                    : { category: text(item.category) }),
+                ...(item.tax === undefined
+                    ? {}
+                    : { taxMinor: moneyFrom(item.tax, money.currency).amountMinor }),
+                ...(item.billing_plan === undefined
+                    ? {}
+                    : { recurringAgreement: recurringFrom(item.billing_plan, money.currency) }),
+            };
+        })
+        : undefined;
+    const quote = {
+        money,
+        ...(Object.keys(rawBreakdown).length ? { breakdown } : {}),
+        ...(items ? { items } : {}),
+    };
+    paypalQuotePayload(quote);
+    const payments = record(unit.payments);
+    if ((unit.payments !== undefined &&
+        (unit.payments === null ||
+            typeof unit.payments !== 'object' ||
+            Array.isArray(unit.payments))) ||
+        (payments.captures !== undefined && !Array.isArray(payments.captures)) ||
+        (payments.authorizations !== undefined && !Array.isArray(payments.authorizations))) {
+        throw approvedOrderError('PRISM_PAYPAL_ORDER_RESPONSE');
+    }
+    const captures = Array.isArray(payments.captures) ? payments.captures : [];
+    const authorizations = Array.isArray(payments.authorizations) ? payments.authorizations : [];
+    if (captures.length > 1)
+        throw approvedOrderError('PRISM_PAYPAL_MULTIPLE_CAPTURES');
+    const statuses = [
+        'CREATED',
+        'SAVED',
+        'PAYER_ACTION_REQUIRED',
+        'APPROVED',
+        'VOIDED',
+        'COMPLETED',
+    ];
+    const orderStatus = statuses.find((status) => status === order.status) ?? 'UNKNOWN';
+    let capture;
+    if (captures.length) {
+        const data = record(captures[0]);
+        const captureMoney = moneyFrom(data.amount, money.currency);
+        if (!text(data.id) ||
+            (data.invoice_id !== undefined && data.invoice_id !== owner.rootOperationId) ||
+            captureMoney.amountMinor !== money.amountMinor) {
+            throw approvedOrderError('PRISM_PAYPAL_CAPTURE_MISMATCH');
+        }
+        const captureStatuses = {
+            COMPLETED: 'captured',
+            PENDING: 'pending',
+            DECLINED: 'failed',
+            FAILED: 'failed',
+            DENIED: 'failed',
+            REFUNDED: 'refunded',
+            PARTIALLY_REFUNDED: 'partially_refunded',
+        };
+        capture = {
+            connectorCaptureId: text(data.id),
+            money: captureMoney,
+            status: captureStatuses[data.status] ?? 'unknown',
+        };
+    }
+    return {
+        connectorPaymentId: owner.connectorPaymentId,
+        rootOperationId: owner.rootOperationId,
+        quote,
+        orderStatus,
+        hasAuthorization: authorizations.length > 0,
+        hasCapture: captures.length > 0,
+        ...(capture
+            ? {
+                capture,
+                connectorMetadata: JSON.stringify({
+                    authorize_id: null,
+                    capture_id: capture.connectorCaptureId,
+                    incremental_authorization_id: null,
+                    psync_flow: 'CAPTURE',
+                    next_action: null,
+                    order_id: null,
+                }),
+            }
+            : {}),
+        ...(typeof order.update_time === 'string' && Number.isFinite(Date.parse(order.update_time))
+            ? { providerUpdatedAt: order.update_time }
+            : {}),
+    };
+}
+//# sourceMappingURL=paypal-approved-order.js.map

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, PrismPayPalOrderLifecycle, PrismPayPalRuntimeVerification, PrismPayPalRuntimeVerificationInput, PrismPaymentResult, PrismRefundInput, PrismRefundResult, PrismRetrieveDisputeInput, PrismRetrieveOrderLifecycleInput, 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, PrismPayPalApprovedOrder, PrismPayPalCaptureApprovedOrderInput, PrismPayPalOrderOwner, PrismPayPalUpdateApprovedOrderInput, 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>;
 }
@@ -32,9 +32,16 @@ export declare class PrismPayPalConnector implements PrismPayPalConnectorV1 {
     private validateOptions;
     private assertOperation;
     private connectorState;
+    private paypalResponse;
     private paypalRequest;
     private retrievePayPalVaultState;
     createPayment(input: PrismMerchantOperation): Promise<PrismPaymentResult>;
+    createAdjustableOrder(input: PrismMerchantOperation): Promise<PrismPaymentResult>;
+    private createPayPalOrder;
+    private assertOrderOwner;
+    retrieveApprovedOrder(input: PrismPayPalOrderOwner): Promise<PrismPayPalApprovedOrder>;
+    updateApprovedOrder(input: PrismPayPalUpdateApprovedOrderInput): Promise<PrismPayPalApprovedOrder>;
+    captureApprovedOrder(input: PrismPayPalCaptureApprovedOrderInput): Promise<PrismPayPalApprovedOrder>;
     authorizeApprovedPayment(input: PrismAuthorizeApprovedPaymentInput): Promise<PrismPaymentResult>;
     repeatPayment(input: PrismMerchantOperation): Promise<PrismPaymentResult>;
     retryPayment(input: PrismRetryPaymentInput): Promise<PrismPaymentResult>;

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

@@ -8,6 +8,14 @@ const proto_1 = require("../payments/generated/proto");
 const error_1 = require("./error");
 const manifest_1 = require("./manifest");
 const money_1 = require("./money");
+const paypal_approved_order_1 = require("./paypal-approved-order");
+function safeProviderIdentifier(value) {
+    if (typeof value !== 'string' || value.length === 0 || value.length > 127)
+        return undefined;
+    return [...value].every((character) => (character >= 'a' && character <= 'z') ||
+        (character >= 'A' && character <= 'Z') ||
+        (character >= '0' && character <= '9') || character === '_' || character === '-') ? value : undefined;
+}
 const PAYPAL_API_BASE = {
     test: 'https://api-m.sandbox.paypal.com',
     live: 'https://api-m.paypal.com',
@@ -253,11 +261,13 @@ function connectorMetadataFrom(response) {
 }
 function failureFrom(response) {
     const error = recordOf(recordOf(response).error);
-    const code = stringOf(error.code);
+    const code = safeProviderIdentifier(recordOf(error.connectorDetails).code) ??
+        safeProviderIdentifier(error.code);
     if (!code && Object.keys(error).length === 0)
         return undefined;
     return {
-        category: 'unknown',
+        category: code === 'INSTRUMENT_DECLINED' ? 'declined' :
+            code === 'PAYER_ACTION_REQUIRED' ? 'customer_action' : 'unknown',
         ...(code ? { providerCode: code } : {}),
         retryable: false,
     };
@@ -363,6 +373,10 @@ function paymentResult(response, money, options, fallbackConnectorPaymentId, app
     const connectorPaymentId = connectorPaymentIdFrom(response) ?? fallbackConnectorPaymentId ?? null;
     const connectorMetadata = connectorMetadataFrom(response);
     const failure = failureFrom(response);
+    const responseData = recordOf(response);
+    const providerRequestId = safeProviderIdentifier(Object.entries(recordOf(responseData.responseHeaders))
+        .find(([key]) => key.toLowerCase() === 'paypal-debug-id')?.[1]);
+    const providerHttpStatus = Number(responseData.statusCode);
     const providerReference = connectorPaymentId
         ? reusableReferenceFrom(response, options, connectorPaymentId)
         : undefined;
@@ -376,6 +390,9 @@ function paymentResult(response, money, options, fallbackConnectorPaymentId, app
         ...(connectorMetadata ? { connectorMetadata } : {}),
         ...(reusableReference ? { reusableReference } : {}),
         ...(failure ? { failure } : {}),
+        ...(providerRequestId ? { providerRequestId } : {}),
+        ...(Number.isInteger(providerHttpStatus) && providerHttpStatus >= 100 && providerHttpStatus <= 599
+            ? { providerHttpStatus } : {}),
     };
 }
 function refundStatus(status) {
@@ -757,7 +774,7 @@ class PrismPayPalConnector {
             },
         };
     }
-    async paypalRequest(method, path, body, idempotencyKey) {
+    async paypalResponse(method, path, body, idempotencyKey) {
         const state = await this.connectorState();
         const accessToken = readSecret(state.accessToken?.token);
         if (!accessToken) {
@@ -776,7 +793,7 @@ class PrismPayPalConnector {
                 ...(body === undefined ? {} : { body: JSON.stringify(body) }),
                 signal: controller.signal,
             });
-            const requestId = response.headers.get('paypal-debug-id') ?? undefined;
+            const requestId = safeProviderIdentifier(response.headers.get('paypal-debug-id'));
             const text = await response.text();
             let payload = null;
             if (text.length > 0) {
@@ -789,22 +806,37 @@ class PrismPayPalConnector {
             }
             if (!response.ok) {
                 const data = recordOf(payload);
+                const issues = (Array.isArray(data.details) ? data.details : [])
+                    .map((detail) => safeProviderIdentifier(recordOf(detail).issue))
+                    .filter((issue) => issue !== undefined)
+                    .slice(0, 10);
+                const providerCode = safeProviderIdentifier(data.name);
+                const providerRequestId = requestId ?? safeProviderIdentifier(data.debug_id);
                 throw new error_1.PrismOperationError({
                     category: response.status === 401 || response.status === 403
                         ? 'authentication'
-                        : response.status === 429
-                            ? 'rate_limited'
-                            : response.status >= 500
-                                ? 'provider_server'
-                                : 'validation',
-                    ...(stringOf(data.name) ? { providerCode: stringOf(data.name) } : {}),
-                    ...(requestId ? { providerRequestId: requestId } : {}),
-                    retryable: response.status === 429 || response.status >= 500,
-                    outcome: response.status >= 500 ? 'ambiguous' : 'definitely_not_applied',
+                        : response.status === 409
+                            ? 'conflict'
+                            : response.status === 429
+                                ? 'rate_limited'
+                                : response.status >= 500
+                                    ? 'provider_server'
+                                    : 'validation',
+                    ...(providerCode ? { providerCode } : {}),
+                    ...(providerRequestId ? { providerRequestId } : {}),
+                    providerHttpStatus: response.status,
+                    ...(issues.length ? { providerIssueCodes: [...new Set(issues)] } : {}),
+                    retryable: response.status === 409 || response.status === 429 || response.status >= 500,
+                    outcome: response.status === 409 || response.status >= 500
+                        ? 'ambiguous' : 'definitely_not_applied',
                     safeMessage: 'PayPal rejected the payment operation.',
                 });
             }
-            return payload;
+            return {
+                payload,
+                providerHttpStatus: response.status,
+                ...(requestId ? { providerRequestId: requestId } : {}),
+            };
         }
         catch (error) {
             throw (0, error_1.normalizePrismError)(error);
@@ -813,11 +845,23 @@ class PrismPayPalConnector {
             clearTimeout(timeout);
         }
     }
+    async paypalRequest(method, path, body, idempotencyKey) {
+        return (await this.paypalResponse(method, path, body, idempotencyKey)).payload;
+    }
     async retrievePayPalVaultState(connectorPaymentId) {
         const payload = await this.paypalRequest('GET', `/v2/checkout/orders/${encodeURIComponent(connectorPaymentId)}?fields=payment_source`);
         return paypalVaultStateFromOrder(payload, this.options, connectorPaymentId);
     }
     async createPayment(input) {
+        return this.createPayPalOrder(input, true);
+    }
+    async createAdjustableOrder(input) {
+        if (input.metadata.alphaweb_capture_method === 'manual') {
+            throw validationError('An adjustable PayPal order must use CAPTURE intent.', 'PRISM_PAYPAL_ORDER_INTENT');
+        }
+        return this.createPayPalOrder(input, false);
+    }
+    async createPayPalOrder(input, commit) {
         this.assertOperation(input);
         if (input.methodSelection.kind !== 'interactive_dynamic' || input.reusableReference) {
             throw validationError('Interactive payment input is invalid.', 'PRISM_INTERACTIVE_INPUT');
@@ -833,7 +877,10 @@ class PrismPayPalConnector {
             const order = await this.dependencies.payments.createOrder({
                 merchantOrderId: input.operationId,
                 amount: moneyMessage(input.money),
-                metadata: secret(JSON.stringify(operationMetadata(input))),
+                metadata: secret(JSON.stringify({
+                    ...operationMetadata(input),
+                    ...(!commit ? { alphaweb_paypal_commit: false } : {}),
+                })),
                 state,
                 testMode: this.options.environment === 'test',
                 paymentMethodType: proto_1.types.PaymentMethodType.PAY_PAL,
@@ -849,6 +896,18 @@ class PrismPayPalConnector {
             });
             const orderId = stringOf(order.connectorOrderId);
             if (!orderId) {
+                if (!commit) {
+                    const result = paymentResult(order, input.money, this.options);
+                    throw new error_1.PrismOperationError({
+                        category: 'unknown',
+                        providerCode: result.failure?.providerCode ?? 'PRISM_PAYPAL_ORDER_CREATE_UNCONFIRMED',
+                        ...(result.providerRequestId ? { providerRequestId: result.providerRequestId } : {}),
+                        ...(result.providerHttpStatus ? { providerHttpStatus: result.providerHttpStatus } : {}),
+                        outcome: 'ambiguous',
+                        retryable: false,
+                        safeMessage: 'The PayPal order creation result must be verified before continuing.',
+                    });
+                }
                 throw validationError('Prism did not return a PayPal order ID.', 'PRISM_PAYPAL_ORDER');
             }
             return {
@@ -863,6 +922,7 @@ class PrismPayPalConnector {
                     clientId: this.options.clientId,
                     environment: this.options.environment === 'test' ? 'sandbox' : 'production',
                     savePayment: setupFutureUsage,
+                    ...(!commit ? { commit: false } : {}),
                 },
             };
         }
@@ -870,6 +930,147 @@ class PrismPayPalConnector {
             throw (0, error_1.normalizePrismError)(error);
         }
     }
+    assertOrderOwner(input) {
+        assertIdentifier(input.rootOperationId, 'rootOperationId');
+        assertIdentifier(input.connectorPaymentId, 'connectorPaymentId');
+        if (input.credentialBindingId !== this.options.credentialBindingId ||
+            input.providerAccountId !== this.options.providerAccountId ||
+            input.livemode !== (this.options.environment === 'live')) {
+            throw (0, paypal_approved_order_1.approvedOrderError)('PRISM_PAYPAL_ORDER_OWNER', 'definitely_not_applied');
+        }
+    }
+    async retrieveApprovedOrder(input) {
+        this.assertOrderOwner(input);
+        const response = await this.paypalResponse('GET', `/v2/checkout/orders/${encodeURIComponent(input.connectorPaymentId)}`);
+        try {
+            return {
+                ...(0, paypal_approved_order_1.readApprovedOrder)(response.payload, input, this.options),
+                ...(response.providerRequestId ? { providerRequestId: response.providerRequestId } : {}),
+            };
+        }
+        catch (error) {
+            const normalized = error instanceof error_1.PrismOperationError
+                ? error : (0, paypal_approved_order_1.approvedOrderError)('PRISM_PAYPAL_ORDER_RESPONSE');
+            throw new error_1.PrismOperationError({
+                ...normalized.shape,
+                outcome: 'ambiguous',
+                providerHttpStatus: response.providerHttpStatus,
+                ...(response.providerRequestId ? { providerRequestId: response.providerRequestId } : {}),
+            });
+        }
+    }
+    async updateApprovedOrder(input) {
+        this.assertOrderOwner(input);
+        const payload = (0, paypal_approved_order_1.paypalQuotePayload)(input.quote);
+        (0, paypal_approved_order_1.assertRecurringDisclosurePreserved)(input.expectedQuote, input.quote);
+        const current = await this.retrieveApprovedOrder(input);
+        if (current.hasCapture || current.hasAuthorization ||
+            (current.orderStatus !== 'CREATED' && current.orderStatus !== 'APPROVED')) {
+            throw (0, paypal_approved_order_1.approvedOrderError)('PRISM_PAYPAL_ORDER_NOT_EDITABLE', 'definitely_not_applied');
+        }
+        if ((0, paypal_approved_order_1.paypalQuotesMatch)(current.quote, input.quote))
+            return current;
+        if (!(0, paypal_approved_order_1.paypalQuotesMatch)(current.quote, input.expectedQuote) ||
+            current.quote.money.currency !== input.quote.money.currency.toLowerCase()) {
+            throw (0, paypal_approved_order_1.approvedOrderError)('PRISM_PAYPAL_ORDER_QUOTE_CHANGED', 'definitely_not_applied');
+        }
+        const base = `/purchase_units/@reference_id=='${input.rootOperationId}'`;
+        const patches = [
+            { op: 'replace', path: `${base}/amount`, value: payload.amount },
+        ];
+        if (payload.items)
+            patches.push({ op: 'add', path: `${base}/items`, value: payload.items });
+        else if (current.quote.items)
+            patches.push({ op: 'remove', path: `${base}/items` });
+        // PATCH has no promised provider idempotency. The caller owns serialization;
+        // after an uncertain result it must retrieve this order before any next quote.
+        const response = await this.paypalResponse('PATCH', `/v2/checkout/orders/${encodeURIComponent(input.connectorPaymentId)}`, patches);
+        let updated;
+        try {
+            updated = await this.retrieveApprovedOrder(input);
+        }
+        catch (error) {
+            // A failed read after an acknowledged PATCH is not a rejected PATCH.
+            throw new error_1.PrismOperationError({
+                ...(0, error_1.normalizePrismError)(error).shape,
+                outcome: 'ambiguous',
+                ...(response.providerRequestId ? { providerRequestId: response.providerRequestId } : {}),
+            });
+        }
+        if (!(0, paypal_approved_order_1.paypalQuotesMatch)(updated.quote, input.quote) || updated.hasCapture || updated.hasAuthorization) {
+            throw new error_1.PrismOperationError({
+                ...(0, paypal_approved_order_1.approvedOrderError)('PRISM_PAYPAL_ORDER_UPDATE_UNCONFIRMED').shape,
+                ...(response.providerRequestId ? { providerRequestId: response.providerRequestId } : {}),
+            });
+        }
+        return {
+            ...updated,
+            ...(response.providerRequestId ? { providerRequestId: response.providerRequestId } : {}),
+        };
+    }
+    async captureApprovedOrder(input) {
+        this.assertOrderOwner(input);
+        assertIdentifier(input.idempotencyKey, 'idempotencyKey');
+        const current = await this.retrieveApprovedOrder(input);
+        if (!(0, paypal_approved_order_1.paypalQuotesMatch)(current.quote, input.quote)) {
+            throw (0, paypal_approved_order_1.approvedOrderError)('PRISM_PAYPAL_ORDER_QUOTE_CHANGED', 'definitely_not_applied');
+        }
+        // A pending capture also owns the payment. Never create a second capture.
+        if (current.hasCapture)
+            return current;
+        if (current.hasAuthorization || current.orderStatus !== 'APPROVED') {
+            throw (0, paypal_approved_order_1.approvedOrderError)('PRISM_PAYPAL_ORDER_NOT_APPROVED', 'definitely_not_applied');
+        }
+        const providerKey = (0, node_crypto_1.createHash)('sha256')
+            .update(JSON.stringify([input.credentialBindingId, input.connectorPaymentId, input.idempotencyKey]))
+            .digest('hex')
+            .slice(0, 32);
+        const result = await this.authorizeApprovedPayment({
+            connectorPaymentId: input.connectorPaymentId,
+            operationId: input.rootOperationId,
+            idempotencyKey: providerKey,
+            money: input.quote.money,
+            captureMethod: 'automatic',
+        });
+        let captured;
+        try {
+            captured = await this.retrieveApprovedOrder(input);
+        }
+        catch (error) {
+            // Capture may already have succeeded; a later GET failure cannot undo it.
+            throw new error_1.PrismOperationError({
+                ...(0, error_1.normalizePrismError)(error).shape,
+                outcome: 'ambiguous',
+                ...(result.providerRequestId ? { providerRequestId: result.providerRequestId } : {}),
+            });
+        }
+        if (!(0, paypal_approved_order_1.paypalQuotesMatch)(captured.quote, input.quote)) {
+            throw (0, paypal_approved_order_1.approvedOrderError)('PRISM_PAYPAL_ORDER_QUOTE_CHANGED');
+        }
+        if (!captured.capture) {
+            if (result.status === 'failed' || result.status === 'requires_payment_method' ||
+                result.status === 'requires_customer_action') {
+                const category = result.status === 'requires_customer_action'
+                    ? 'customer_action' : result.failure?.category ?? 'unknown';
+                throw new error_1.PrismOperationError({
+                    category: category === 'invalid_payment_method' ? 'validation' : category,
+                    providerCode: result.failure?.providerCode ?? 'PRISM_PAYPAL_CAPTURE_NOT_COMPLETED',
+                    ...(result.providerRequestId ? { providerRequestId: result.providerRequestId } : {}),
+                    ...(result.providerHttpStatus ? { providerHttpStatus: result.providerHttpStatus } : {}),
+                    retryable: false,
+                    outcome: category === 'unknown' ? 'ambiguous' : 'definitely_not_applied',
+                    safeMessage: result.status === 'requires_customer_action'
+                        ? 'PayPal requires customer action to complete this payment.'
+                        : 'PayPal did not complete this payment.',
+                });
+            }
+            throw (0, paypal_approved_order_1.approvedOrderError)('PRISM_PAYPAL_CAPTURE_UNCONFIRMED');
+        }
+        return {
+            ...captured,
+            ...(result.providerRequestId ? { providerRequestId: result.providerRequestId } : {}),
+        };
+    }
     async authorizeApprovedPayment(input) {
         assertIdentifier(input.operationId, 'operationId');
         assertIdentifier(input.idempotencyKey, 'idempotencyKey');

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

@@ -5,7 +5,7 @@ export type PrismEnvironment = 'test' | 'live';
  * payment contract a Stripe/PayPal-only union.
  */
 export type PrismConnectorId = string;
-export type PrismOperationKind = 'checkout' | 'post_purchase' | 'subscription_renewal' | 'refund' | 'cancel';
+export type PrismOperationKind = 'checkout' | 'combined_checkout' | 'post_purchase' | 'subscription_renewal' | 'refund' | 'cancel';
 export interface PrismMoney {
     amountMinor: string;
     currency: string;
@@ -58,6 +58,8 @@ export interface PrismPayPalBrowserSession {
     clientId: string;
     environment: 'sandbox' | 'production';
     savePayment: boolean;
+    /** False for an approved order whose final total is selected before capture. */
+    commit?: boolean;
 }
 /**
  * Declaration-merging extension point for future qualified connectors.
@@ -117,6 +119,7 @@ export interface PrismPaymentResult {
     connectorMetadata?: string;
     reusableReference?: PrismReusablePaymentReference;
     providerRequestId?: string;
+    providerHttpStatus?: number;
     failure?: PrismPaymentFailure;
 }
 export interface PrismRefundResult {
@@ -334,9 +337,69 @@ export interface PrismPayPalOrderLifecycle {
 export interface PrismRetrieveOrderLifecycleInput {
     connectorPaymentId: string;
 }
+export interface PrismPayPalOrderItem {
+    name: string;
+    sku?: string;
+    category?: 'DIGITAL_GOODS' | 'PHYSICAL_GOODS' | 'DONATION';
+    quantity: number;
+    unitAmountMinor: string;
+    taxMinor?: string;
+    /** Existing merchant-managed recurring disclosure; never inferred from an OTO total. */
+    recurringAgreement?: PrismRecurringAgreement;
+}
+export interface PrismPayPalOrderQuote {
+    money: PrismMoney;
+    breakdown?: {
+        itemTotalMinor?: string;
+        taxTotalMinor?: string;
+        shippingMinor?: string;
+        handlingMinor?: string;
+        insuranceMinor?: string;
+        shippingDiscountMinor?: string;
+        discountMinor?: string;
+    };
+    items?: PrismPayPalOrderItem[];
+}
+export interface PrismPayPalOrderOwner {
+    connectorPaymentId: string;
+    /** The original order-creation operation, never the later adjustment/capture. */
+    rootOperationId: string;
+    credentialBindingId: string;
+    providerAccountId: string;
+    livemode: boolean;
+    expectedCustomId?: string;
+}
+export interface PrismPayPalApprovedOrder extends PrismPayPalOrderLifecycle {
+    connectorPaymentId: string;
+    rootOperationId: string;
+    quote: PrismPayPalOrderQuote;
+    providerUpdatedAt?: string;
+    providerRequestId?: string;
+    /** Native Prism metadata, retained for refunds even after a lost capture response. */
+    connectorMetadata?: string;
+    capture?: {
+        connectorCaptureId: string;
+        status: 'pending' | 'captured' | 'failed' | 'refunded' | 'partially_refunded' | 'unknown';
+        money: PrismMoney;
+    };
+}
+export interface PrismPayPalUpdateApprovedOrderInput extends PrismPayPalOrderOwner {
+    expectedQuote: PrismPayPalOrderQuote;
+    quote: PrismPayPalOrderQuote;
+}
+export interface PrismPayPalCaptureApprovedOrderInput extends PrismPayPalOrderOwner {
+    quote: PrismPayPalOrderQuote;
+    /** Persist once for the final capture; must not change when a claim is renewed. */
+    idempotencyKey: string;
+}
 export interface PrismPayPalConnectorV1 extends PrismConnectorV1 {
     authorizeApprovedPayment(input: PrismAuthorizeApprovedPaymentInput): Promise<PrismPaymentResult>;
     retrieveOrderLifecycle?(input: PrismRetrieveOrderLifecycleInput): Promise<PrismPayPalOrderLifecycle>;
+    createAdjustableOrder?(input: PrismMerchantOperation): Promise<PrismPaymentResult>;
+    retrieveApprovedOrder?(input: PrismPayPalOrderOwner): Promise<PrismPayPalApprovedOrder>;
+    /** Caller serializes decisions and reconciles an uncertain PATCH before another mutation. */
+    updateApprovedOrder?(input: PrismPayPalUpdateApprovedOrderInput): Promise<PrismPayPalApprovedOrder>;
+    captureApprovedOrder?(input: PrismPayPalCaptureApprovedOrderInput): Promise<PrismPayPalApprovedOrder>;
 }
 export interface PrismStripeConnectorOptions {
     environment: PrismEnvironment;

package/package.json

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