@proxy-checkout/server-js 0.0.7 → 0.0.8-prx-109.81.1

package/README.md

@@ -35,7 +35,11 @@ const proxy = createProxyCheckoutServerClient({
 
 const handoff = await proxy.sessions.createHandoff({
   amountMinor: 5000,
+  // Stable, non-PII entitlement owner reference. For pre-account flows,
+  // use a pending entitlement id instead of an email address.
   buyerReference: "buyer_123",
+  // Optional beneficiary contact for the person receiving access.
+  beneficiaryContact: { email: "recipient@example.com" },
   currency: "usd",
   cartSnapshot: {
     items: [{ product_id: "prod_123", quantity: 1 }],
@@ -70,6 +74,29 @@ For delegated checkout, prefer the high-level flow:
 
 Use `payerHandoff`, `payerOpened`, raw event construction, or manual provisioning acknowledgements only for custom integrations that cannot use the default helpers.
 
+`proxy.webhooks.handle(...)` automatically marks successful initial provisioning as provisioned after `onResolved` completes. Return a fulfillment reference and/or metadata from `onResolved` when you want that acknowledgement to record the merchant-side access row:
+
+```ts
+await proxy.webhooks.handle(request, {
+  secret: process.env.PROXY_WEBHOOK_SIGNING_SECRET!,
+  async onResolved(resolved) {
+    if (resolved.kind !== "initial_provision") {
+      return;
+    }
+
+    const entitlement = await grantOrMarkPending(resolved.session);
+    return {
+      fulfillmentReference: entitlement.id,
+      metadata: { claim_status: entitlement.profileId ? "claimed" : "pending_account_claim" },
+    };
+  },
+});
+```
+
+`fulfillmentReference` is copied to Proxy's `proxy_session.provisioned` session/audit event. Use it for support and reconciliation, for example "Proxy session `psess_...` was fulfilled by Fiveable pending entitlement `pent_...`." It does not grant access and is not used for future claim validation.
+
+For pre-account purchases, create a durable pending entitlement before `sessions.createHandoff(...)`, use that pending entitlement id as `buyerReference`, pass the future recipient's contact as `beneficiaryContact`, and claim the entitlement after signup/login with your own high-entropy claim token. Store only the token hash on the pending entitlement; use `sessionStorage` or an emailed merchant-owned claim link to carry the plaintext token to the authenticated claim endpoint. Treat `proxy_session_id` as public correlation, not as a claim secret.
+
 Verify and parse outbound webhooks with the exact raw request body:
 
 ```ts

package/dist/cjs/index.d.cts

@@ -9,5 +9,5 @@ export { type MerchantProxySubscription, ProxySubscriptionsResource, type ProxyS
 export type { JsonObject, JsonPrimitive, JsonValue, ProxyCheckoutFetch, ProxyCheckoutServerClientOptions, ProxyCheckoutServerRequestOptions, } from "./types.js";
 export { proxyCheckoutServerSdkName, proxyCheckoutServerSdkUserAgent, proxyCheckoutServerSdkVersion, } from "./version.js";
 export { isProxyPaymentAttemptEvent, isProxySessionEvent, isProxySubscriptionEvent, PROXY_WEBHOOK_EVENT_TYPES, type ProxyWebhookEventType, } from "./webhook-events.js";
-export { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, type ProxyWebhookClaimResult, type ProxyWebhookHandlerOptions, type ProxyWebhookOutcome, type ProxyWebhookPayloadInput, type ProxyWebhookProcessRecord, type ProxyWebhookProcessResult, type ProxyWebhookProvisioningFailure, type ProxyWebhookRequestInput, type ProxyWebhookStore, ProxyWebhooksResource, } from "./webhook-handler.js";
+export { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, type ProxyWebhookClaimResult, type ProxyWebhookHandlerOptions, type ProxyWebhookOutcome, type ProxyWebhookPayloadInput, type ProxyWebhookProcessRecord, type ProxyWebhookProcessResult, type ProxyWebhookProvisioningFailure, type ProxyWebhookProvisioningSuccess, type ProxyWebhookProvisioningSuccessResult, type ProxyWebhookRequestInput, type ProxyWebhookStore, ProxyWebhooksResource, } from "./webhook-handler.js";
 export { type ConstructProxyWebhookEventInput, type CreateWebhookEndpointInput, constructProxyWebhookEvent, PROXY_SIGNATURE_HEADER, ProxyWebhookEndpointsResource, type ProxyWebhookEvent, ProxyWebhookSignatureVerificationError, proxyCheckoutWebhookEndpointEndpoints, type RotateWebhookEndpointSecretInput, type UpdateWebhookEndpointInput, type VerifyProxyWebhookSignatureInput, verifyProxyWebhookSignature, type WebhookEndpoint, type WebhookEndpointSecretResult, } from "./webhooks.js";

package/dist/cjs/index.d.ts

@@ -9,5 +9,5 @@ export { type MerchantProxySubscription, ProxySubscriptionsResource, type ProxyS
 export type { JsonObject, JsonPrimitive, JsonValue, ProxyCheckoutFetch, ProxyCheckoutServerClientOptions, ProxyCheckoutServerRequestOptions, } from "./types.js";
 export { proxyCheckoutServerSdkName, proxyCheckoutServerSdkUserAgent, proxyCheckoutServerSdkVersion, } from "./version.js";
 export { isProxyPaymentAttemptEvent, isProxySessionEvent, isProxySubscriptionEvent, PROXY_WEBHOOK_EVENT_TYPES, type ProxyWebhookEventType, } from "./webhook-events.js";
-export { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, type ProxyWebhookClaimResult, type ProxyWebhookHandlerOptions, type ProxyWebhookOutcome, type ProxyWebhookPayloadInput, type ProxyWebhookProcessRecord, type ProxyWebhookProcessResult, type ProxyWebhookProvisioningFailure, type ProxyWebhookRequestInput, type ProxyWebhookStore, ProxyWebhooksResource, } from "./webhook-handler.js";
+export { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, type ProxyWebhookClaimResult, type ProxyWebhookHandlerOptions, type ProxyWebhookOutcome, type ProxyWebhookPayloadInput, type ProxyWebhookProcessRecord, type ProxyWebhookProcessResult, type ProxyWebhookProvisioningFailure, type ProxyWebhookProvisioningSuccess, type ProxyWebhookProvisioningSuccessResult, type ProxyWebhookRequestInput, type ProxyWebhookStore, ProxyWebhooksResource, } from "./webhook-handler.js";
 export { type ConstructProxyWebhookEventInput, type CreateWebhookEndpointInput, constructProxyWebhookEvent, PROXY_SIGNATURE_HEADER, ProxyWebhookEndpointsResource, type ProxyWebhookEvent, ProxyWebhookSignatureVerificationError, proxyCheckoutWebhookEndpointEndpoints, type RotateWebhookEndpointSecretInput, type UpdateWebhookEndpointInput, type VerifyProxyWebhookSignatureInput, verifyProxyWebhookSignature, type WebhookEndpoint, type WebhookEndpointSecretResult, } from "./webhooks.js";

package/dist/cjs/sessions.d.cts

@@ -6,6 +6,10 @@ export interface CreateProxySessionOptions extends ProxyCheckoutServerRequestOpt
 }
 export interface CreateProxySessionInput extends CreateProxySessionOptions {
     readonly amountMinor: number;
+    readonly beneficiaryContact?: {
+        readonly email?: string;
+        readonly phone?: string;
+    };
     readonly buyerReference: string;
     readonly cartSnapshot: JsonObject;
     readonly currency: string;
@@ -34,6 +38,10 @@ export interface ProxySessionHandoff extends ProxySession {
 }
 export interface MerchantProxySession {
     readonly amountMinor: number;
+    readonly beneficiaryContact: {
+        readonly email: string | null;
+        readonly phone: string | null;
+    } | null;
     readonly buyerReference: string;
     readonly cartSnapshot: JsonObject;
     readonly cartVersion: number;
@@ -87,7 +95,14 @@ export interface ProxySessionProviderBinding {
     readonly updatedAt: string;
 }
 export interface MarkProxySessionProvisionedInput extends ProxyCheckoutServerRequestOptions {
+    /**
+     * Optional merchant-side fulfillment row id to store on Proxy's provisioned
+     * session/audit event, for example a pending entitlement id or durable role
+     * id. This is for support and reconciliation only; do not put claim tokens or
+     * secrets here.
+     */
     readonly fulfillmentReference?: string;
+    /** Optional non-secret metadata to store with the provisioned acknowledgement. */
     readonly metadata?: JsonObject;
 }
 export interface MarkProxySessionProvisioningFailedInput extends ProxyCheckoutServerRequestOptions {

package/dist/cjs/sessions.d.ts

@@ -6,6 +6,10 @@ export interface CreateProxySessionOptions extends ProxyCheckoutServerRequestOpt
 }
 export interface CreateProxySessionInput extends CreateProxySessionOptions {
     readonly amountMinor: number;
+    readonly beneficiaryContact?: {
+        readonly email?: string;
+        readonly phone?: string;
+    };
     readonly buyerReference: string;
     readonly cartSnapshot: JsonObject;
     readonly currency: string;
@@ -34,6 +38,10 @@ export interface ProxySessionHandoff extends ProxySession {
 }
 export interface MerchantProxySession {
     readonly amountMinor: number;
+    readonly beneficiaryContact: {
+        readonly email: string | null;
+        readonly phone: string | null;
+    } | null;
     readonly buyerReference: string;
     readonly cartSnapshot: JsonObject;
     readonly cartVersion: number;
@@ -87,7 +95,14 @@ export interface ProxySessionProviderBinding {
     readonly updatedAt: string;
 }
 export interface MarkProxySessionProvisionedInput extends ProxyCheckoutServerRequestOptions {
+    /**
+     * Optional merchant-side fulfillment row id to store on Proxy's provisioned
+     * session/audit event, for example a pending entitlement id or durable role
+     * id. This is for support and reconciliation only; do not put claim tokens or
+     * secrets here.
+     */
     readonly fulfillmentReference?: string;
+    /** Optional non-secret metadata to store with the provisioned acknowledgement. */
     readonly metadata?: JsonObject;
 }
 export interface MarkProxySessionProvisioningFailedInput extends ProxyCheckoutServerRequestOptions {

package/dist/cjs/sessions.js

@@ -196,6 +196,12 @@ function toCreateProxySessionBody(input) {
         cart_snapshot: input.cartSnapshot,
         currency: input.currency,
     };
+    if (input.beneficiaryContact !== undefined) {
+        body.beneficiary_contact = removeUndefinedValues({
+            email: input.beneficiaryContact.email,
+            phone: input.beneficiaryContact.phone,
+        });
+    }
     if (input.expiresAt !== undefined) {
         body.expires_at =
             input.expiresAt instanceof Date ? input.expiresAt.toISOString() : input.expiresAt;
@@ -256,6 +262,7 @@ function toMerchantProxySession(response) {
     const body = (0, response_validators_js_1.requireJsonObject)(response, "sessions.retrieve");
     return {
         amountMinor: (0, response_validators_js_1.requireInteger)(body.amount_minor, "sessions.retrieve.amountMinor"),
+        beneficiaryContact: requireNullableContact(body.beneficiary_contact, "sessions.retrieve.beneficiaryContact"),
         buyerReference: (0, response_validators_js_1.requireString)(body.buyer_reference, "sessions.retrieve.buyerReference"),
         cartSnapshot: (0, response_validators_js_1.requireJsonObject)(body.cart_snapshot, "sessions.retrieve.cartSnapshot"),
         cartVersion: (0, response_validators_js_1.requireInteger)(body.cart_version, "sessions.retrieve.cartVersion"),
@@ -266,7 +273,7 @@ function toMerchantProxySession(response) {
         idempotencyKey: (0, response_validators_js_1.requireNullableString)(body.idempotency_key, "sessions.retrieve.idempotencyKey"),
         integrationMode: (0, response_validators_js_1.requireString)(body.integration_mode, "sessions.retrieve.integrationMode"),
         metadata: (0, response_validators_js_1.requireJsonObject)(body.metadata, "sessions.retrieve.metadata"),
-        payerContact: requireNullablePayerContact(body.payer_contact),
+        payerContact: requireNullableContact(body.payer_contact, "sessions.retrieve.payerContact"),
         payerDestinationUrl: (0, response_validators_js_1.requireNullableString)(body.payer_destination_url, "sessions.retrieve.payerDestinationUrl"),
         providerCheckoutSessionId: (0, response_validators_js_1.requireNullableString)(body.provider_checkout_session_id, "sessions.retrieve.providerCheckoutSessionId"),
         providerCheckoutSessionPsp: (0, response_validators_js_1.requireNullableString)(body.provider_checkout_session_psp, "sessions.retrieve.providerCheckoutSessionPsp"),
@@ -282,6 +289,7 @@ function toPayerOpenedResult(response) {
     }
     return {
         amountMinor: (0, response_validators_js_1.requireInteger)(body.amount_minor, "sessions.payerOpened.amountMinor"),
+        beneficiaryContact: requireNullableContact(body.beneficiary_contact, "sessions.payerOpened.beneficiaryContact"),
         buyerReference: (0, response_validators_js_1.requireString)(body.buyer_reference, "sessions.payerOpened.buyerReference"),
         cartSnapshot: (0, response_validators_js_1.requireJsonObject)(body.cart_snapshot, "sessions.payerOpened.cartSnapshot"),
         cartVersion: (0, response_validators_js_1.requireInteger)(body.cart_version, "sessions.payerOpened.cartVersion"),
@@ -292,7 +300,7 @@ function toPayerOpenedResult(response) {
         idempotencyKey: (0, response_validators_js_1.requireNullableString)(body.idempotency_key, "sessions.payerOpened.idempotencyKey"),
         integrationMode: (0, response_validators_js_1.requireString)(body.integration_mode, "sessions.payerOpened.integrationMode"),
         metadata: (0, response_validators_js_1.requireJsonObject)(body.metadata, "sessions.payerOpened.metadata"),
-        payerContact: requireNullablePayerContact(body.payer_contact, "sessions.payerOpened"),
+        payerContact: requireNullableContact(body.payer_contact, "sessions.payerOpened.payerContact"),
         payerDestinationUrl: (0, response_validators_js_1.requireNullableString)(body.payer_destination_url, "sessions.payerOpened.payerDestinationUrl"),
         providerCheckoutSessionId: (0, response_validators_js_1.requireNullableString)(body.provider_checkout_session_id, "sessions.payerOpened.providerCheckoutSessionId"),
         providerCheckoutSessionPsp: (0, response_validators_js_1.requireNullableString)(body.provider_checkout_session_psp, "sessions.payerOpened.providerCheckoutSessionPsp"),
@@ -300,14 +308,14 @@ function toPayerOpenedResult(response) {
         updatedAt: (0, response_validators_js_1.requireString)(body.updated_at, "sessions.payerOpened.updatedAt"),
     };
 }
-function requireNullablePayerContact(value, operation = "sessions.retrieve") {
-    if (value === null) {
+function requireNullableContact(value, field) {
+    if (value === null || value === undefined) {
         return null;
     }
-    const contact = (0, response_validators_js_1.requireJsonObject)(value, `${operation}.payerContact`);
+    const contact = (0, response_validators_js_1.requireJsonObject)(value, field);
     return {
-        email: (0, response_validators_js_1.requireNullableString)(contact.email, `${operation}.payerContact.email`),
-        phone: (0, response_validators_js_1.requireNullableString)(contact.phone, `${operation}.payerContact.phone`),
+        email: (0, response_validators_js_1.requireNullableString)(contact.email, `${field}.email`),
+        phone: (0, response_validators_js_1.requireNullableString)(contact.phone, `${field}.phone`),
     };
 }
 function requirePayerHandoffStatus(value) {

package/dist/cjs/version.d.cts

@@ -1,3 +1,3 @@
 export declare const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export declare const proxyCheckoutServerSdkVersion = "0.0.7";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.7";
+export declare const proxyCheckoutServerSdkVersion = "0.0.8-prx-109.81.1";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.8-prx-109.81.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.7";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.7";
+export declare const proxyCheckoutServerSdkVersion = "0.0.8-prx-109.81.1";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.8-prx-109.81.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.7";
+exports.proxyCheckoutServerSdkVersion = "0.0.8-prx-109.81.1";
 exports.proxyCheckoutServerSdkUserAgent = `${exports.proxyCheckoutServerSdkName}/${exports.proxyCheckoutServerSdkVersion}`;

package/dist/cjs/webhook-handler.d.cts

@@ -40,6 +40,20 @@ export interface ProxyWebhookProvisioningFailure {
     readonly errorMessage: string;
     readonly metadata?: JsonObject;
 }
+/**
+ * Optional data recorded when the handler acknowledges successful initial
+ * provisioning back to Proxy. This is audit/reconciliation data only. It does
+ * not grant access, does not participate in future claim-token validation, and
+ * should not contain secrets.
+ */
+export interface ProxyWebhookProvisioningSuccess {
+    /** Stable merchant-side row id that fulfilled the session, such as a pending entitlement or role id. */
+    readonly fulfillmentReference?: string;
+    /** Small non-secret facts to store on Proxy's provisioned session/audit event. */
+    readonly metadata?: JsonObject;
+}
+type ProxyWebhookNoProvisioningMetadataResult = void;
+export type ProxyWebhookProvisioningSuccessResult = ProxyWebhookProvisioningSuccess | null | undefined | ProxyWebhookNoProvisioningMetadataResult;
 export interface ProxyWebhookPayloadInput {
     readonly body: Buffer | string;
     readonly signature?: string | null;
@@ -56,8 +70,14 @@ export interface ProxyWebhookHandlerOptions {
      * failure payload only after the merchant knows retrying cannot grant access.
      */
     readonly classifyProvisioningFailure?: (error: unknown, resolved: ResolvedProxyEvent) => Promise<ProxyWebhookProvisioningFailure | null | undefined> | ProxyWebhookProvisioningFailure | null | undefined;
-    /** Merchant entitlement callback, invoked once per claimed event after current-state resolution. */
-    readonly onResolved: (resolved: ResolvedProxyEvent) => Promise<void> | void;
+    /**
+     * Merchant entitlement callback, invoked once per claimed event after
+     * current-state resolution. For initial provisioning, mutate the merchant's
+     * entitlement store first, then optionally return the merchant-side row id
+     * and non-secret metadata to record on Proxy's provisioned acknowledgement.
+     * Do not return claim tokens or other secrets here.
+     */
+    readonly onResolved: (resolved: ResolvedProxyEvent) => Promise<ProxyWebhookProvisioningSuccessResult> | ProxyWebhookProvisioningSuccessResult;
     /** Optional request id forwarded to the current-state retrieval calls. */
     readonly requestId?: string;
     /** Endpoint signing secret. */
@@ -102,3 +122,4 @@ export declare class ProxyWebhooksResource {
     private runResolvedHandler;
     private requireSessionsResource;
 }
+export {};

package/dist/cjs/webhook-handler.d.ts

@@ -40,6 +40,20 @@ export interface ProxyWebhookProvisioningFailure {
     readonly errorMessage: string;
     readonly metadata?: JsonObject;
 }
+/**
+ * Optional data recorded when the handler acknowledges successful initial
+ * provisioning back to Proxy. This is audit/reconciliation data only. It does
+ * not grant access, does not participate in future claim-token validation, and
+ * should not contain secrets.
+ */
+export interface ProxyWebhookProvisioningSuccess {
+    /** Stable merchant-side row id that fulfilled the session, such as a pending entitlement or role id. */
+    readonly fulfillmentReference?: string;
+    /** Small non-secret facts to store on Proxy's provisioned session/audit event. */
+    readonly metadata?: JsonObject;
+}
+type ProxyWebhookNoProvisioningMetadataResult = void;
+export type ProxyWebhookProvisioningSuccessResult = ProxyWebhookProvisioningSuccess | null | undefined | ProxyWebhookNoProvisioningMetadataResult;
 export interface ProxyWebhookPayloadInput {
     readonly body: Buffer | string;
     readonly signature?: string | null;
@@ -56,8 +70,14 @@ export interface ProxyWebhookHandlerOptions {
      * failure payload only after the merchant knows retrying cannot grant access.
      */
     readonly classifyProvisioningFailure?: (error: unknown, resolved: ResolvedProxyEvent) => Promise<ProxyWebhookProvisioningFailure | null | undefined> | ProxyWebhookProvisioningFailure | null | undefined;
-    /** Merchant entitlement callback, invoked once per claimed event after current-state resolution. */
-    readonly onResolved: (resolved: ResolvedProxyEvent) => Promise<void> | void;
+    /**
+     * Merchant entitlement callback, invoked once per claimed event after
+     * current-state resolution. For initial provisioning, mutate the merchant's
+     * entitlement store first, then optionally return the merchant-side row id
+     * and non-secret metadata to record on Proxy's provisioned acknowledgement.
+     * Do not return claim tokens or other secrets here.
+     */
+    readonly onResolved: (resolved: ResolvedProxyEvent) => Promise<ProxyWebhookProvisioningSuccessResult> | ProxyWebhookProvisioningSuccessResult;
     /** Optional request id forwarded to the current-state retrieval calls. */
     readonly requestId?: string;
     /** Endpoint signing secret. */
@@ -102,3 +122,4 @@ export declare class ProxyWebhooksResource {
     private runResolvedHandler;
     private requireSessionsResource;
 }
+export {};

package/dist/cjs/webhook-handler.js

@@ -64,9 +64,11 @@ class ProxyWebhooksResource {
         let resolved;
         try {
             resolved = await this.events.resolveCurrentState(event, { requestId: options.requestId });
-            const provisioningFailed = await this.runResolvedHandler(resolved, options);
-            if (!provisioningFailed && resolved.kind === "initial_provision") {
+            const provisioning = await this.runResolvedHandler(resolved, options);
+            if (!provisioning.failed && resolved.kind === "initial_provision") {
                 await this.requireSessionsResource("mark provisioned").markProvisioned(resolved.session.id, {
+                    fulfillmentReference: provisioning.success?.fulfillmentReference,
+                    metadata: provisioning.success?.metadata,
                     requestId: options.requestId,
                 });
             }
@@ -130,8 +132,11 @@ class ProxyWebhooksResource {
     }
     async runResolvedHandler(resolved, options) {
         try {
-            await options.onResolved(resolved);
-            return false;
+            const success = await options.onResolved(resolved);
+            return {
+                failed: false,
+                success: normalizeProvisioningSuccess(success),
+            };
         }
         catch (error) {
             if (resolved.kind !== "initial_provision" || !options.classifyProvisioningFailure) {
@@ -147,7 +152,7 @@ class ProxyWebhooksResource {
                 metadata: failure.metadata,
                 requestId: options.requestId,
             });
-            return true;
+            return { failed: true };
         }
     }
     requireSessionsResource(operation) {
@@ -160,6 +165,21 @@ class ProxyWebhooksResource {
     }
 }
 exports.ProxyWebhooksResource = ProxyWebhooksResource;
+function normalizeProvisioningSuccess(value) {
+    if (value == null) {
+        return undefined;
+    }
+    const success = {};
+    if (value.fulfillmentReference !== undefined) {
+        success.fulfillmentReference = value.fulfillmentReference;
+    }
+    if (value.metadata !== undefined) {
+        success.metadata = value.metadata;
+    }
+    return success.fulfillmentReference === undefined && success.metadata === undefined
+        ? undefined
+        : success;
+}
 function toWebhookResponse(result) {
     const headers = { "content-type": "application/json" };
     if (result.retryable) {

package/dist/esm/index.d.ts

@@ -9,5 +9,5 @@ export { type MerchantProxySubscription, ProxySubscriptionsResource, type ProxyS
 export type { JsonObject, JsonPrimitive, JsonValue, ProxyCheckoutFetch, ProxyCheckoutServerClientOptions, ProxyCheckoutServerRequestOptions, } from "./types.js";
 export { proxyCheckoutServerSdkName, proxyCheckoutServerSdkUserAgent, proxyCheckoutServerSdkVersion, } from "./version.js";
 export { isProxyPaymentAttemptEvent, isProxySessionEvent, isProxySubscriptionEvent, PROXY_WEBHOOK_EVENT_TYPES, type ProxyWebhookEventType, } from "./webhook-events.js";
-export { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, type ProxyWebhookClaimResult, type ProxyWebhookHandlerOptions, type ProxyWebhookOutcome, type ProxyWebhookPayloadInput, type ProxyWebhookProcessRecord, type ProxyWebhookProcessResult, type ProxyWebhookProvisioningFailure, type ProxyWebhookRequestInput, type ProxyWebhookStore, ProxyWebhooksResource, } from "./webhook-handler.js";
+export { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, type ProxyWebhookClaimResult, type ProxyWebhookHandlerOptions, type ProxyWebhookOutcome, type ProxyWebhookPayloadInput, type ProxyWebhookProcessRecord, type ProxyWebhookProcessResult, type ProxyWebhookProvisioningFailure, type ProxyWebhookProvisioningSuccess, type ProxyWebhookProvisioningSuccessResult, type ProxyWebhookRequestInput, type ProxyWebhookStore, ProxyWebhooksResource, } from "./webhook-handler.js";
 export { type ConstructProxyWebhookEventInput, type CreateWebhookEndpointInput, constructProxyWebhookEvent, PROXY_SIGNATURE_HEADER, ProxyWebhookEndpointsResource, type ProxyWebhookEvent, ProxyWebhookSignatureVerificationError, proxyCheckoutWebhookEndpointEndpoints, type RotateWebhookEndpointSecretInput, type UpdateWebhookEndpointInput, type VerifyProxyWebhookSignatureInput, verifyProxyWebhookSignature, type WebhookEndpoint, type WebhookEndpointSecretResult, } from "./webhooks.js";

package/dist/esm/sessions.d.ts

@@ -6,6 +6,10 @@ export interface CreateProxySessionOptions extends ProxyCheckoutServerRequestOpt
 }
 export interface CreateProxySessionInput extends CreateProxySessionOptions {
     readonly amountMinor: number;
+    readonly beneficiaryContact?: {
+        readonly email?: string;
+        readonly phone?: string;
+    };
     readonly buyerReference: string;
     readonly cartSnapshot: JsonObject;
     readonly currency: string;
@@ -34,6 +38,10 @@ export interface ProxySessionHandoff extends ProxySession {
 }
 export interface MerchantProxySession {
     readonly amountMinor: number;
+    readonly beneficiaryContact: {
+        readonly email: string | null;
+        readonly phone: string | null;
+    } | null;
     readonly buyerReference: string;
     readonly cartSnapshot: JsonObject;
     readonly cartVersion: number;
@@ -87,7 +95,14 @@ export interface ProxySessionProviderBinding {
     readonly updatedAt: string;
 }
 export interface MarkProxySessionProvisionedInput extends ProxyCheckoutServerRequestOptions {
+    /**
+     * Optional merchant-side fulfillment row id to store on Proxy's provisioned
+     * session/audit event, for example a pending entitlement id or durable role
+     * id. This is for support and reconciliation only; do not put claim tokens or
+     * secrets here.
+     */
     readonly fulfillmentReference?: string;
+    /** Optional non-secret metadata to store with the provisioned acknowledgement. */
     readonly metadata?: JsonObject;
 }
 export interface MarkProxySessionProvisioningFailedInput extends ProxyCheckoutServerRequestOptions {

package/dist/esm/sessions.js

@@ -191,6 +191,12 @@ function toCreateProxySessionBody(input) {
         cart_snapshot: input.cartSnapshot,
         currency: input.currency,
     };
+    if (input.beneficiaryContact !== undefined) {
+        body.beneficiary_contact = removeUndefinedValues({
+            email: input.beneficiaryContact.email,
+            phone: input.beneficiaryContact.phone,
+        });
+    }
     if (input.expiresAt !== undefined) {
         body.expires_at =
             input.expiresAt instanceof Date ? input.expiresAt.toISOString() : input.expiresAt;
@@ -251,6 +257,7 @@ function toMerchantProxySession(response) {
     const body = requireJsonObject(response, "sessions.retrieve");
     return {
         amountMinor: requireInteger(body.amount_minor, "sessions.retrieve.amountMinor"),
+        beneficiaryContact: requireNullableContact(body.beneficiary_contact, "sessions.retrieve.beneficiaryContact"),
         buyerReference: requireString(body.buyer_reference, "sessions.retrieve.buyerReference"),
         cartSnapshot: requireJsonObject(body.cart_snapshot, "sessions.retrieve.cartSnapshot"),
         cartVersion: requireInteger(body.cart_version, "sessions.retrieve.cartVersion"),
@@ -261,7 +268,7 @@ function toMerchantProxySession(response) {
         idempotencyKey: requireNullableString(body.idempotency_key, "sessions.retrieve.idempotencyKey"),
         integrationMode: requireString(body.integration_mode, "sessions.retrieve.integrationMode"),
         metadata: requireJsonObject(body.metadata, "sessions.retrieve.metadata"),
-        payerContact: requireNullablePayerContact(body.payer_contact),
+        payerContact: requireNullableContact(body.payer_contact, "sessions.retrieve.payerContact"),
         payerDestinationUrl: requireNullableString(body.payer_destination_url, "sessions.retrieve.payerDestinationUrl"),
         providerCheckoutSessionId: requireNullableString(body.provider_checkout_session_id, "sessions.retrieve.providerCheckoutSessionId"),
         providerCheckoutSessionPsp: requireNullableString(body.provider_checkout_session_psp, "sessions.retrieve.providerCheckoutSessionPsp"),
@@ -277,6 +284,7 @@ function toPayerOpenedResult(response) {
     }
     return {
         amountMinor: requireInteger(body.amount_minor, "sessions.payerOpened.amountMinor"),
+        beneficiaryContact: requireNullableContact(body.beneficiary_contact, "sessions.payerOpened.beneficiaryContact"),
         buyerReference: requireString(body.buyer_reference, "sessions.payerOpened.buyerReference"),
         cartSnapshot: requireJsonObject(body.cart_snapshot, "sessions.payerOpened.cartSnapshot"),
         cartVersion: requireInteger(body.cart_version, "sessions.payerOpened.cartVersion"),
@@ -287,7 +295,7 @@ function toPayerOpenedResult(response) {
         idempotencyKey: requireNullableString(body.idempotency_key, "sessions.payerOpened.idempotencyKey"),
         integrationMode: requireString(body.integration_mode, "sessions.payerOpened.integrationMode"),
         metadata: requireJsonObject(body.metadata, "sessions.payerOpened.metadata"),
-        payerContact: requireNullablePayerContact(body.payer_contact, "sessions.payerOpened"),
+        payerContact: requireNullableContact(body.payer_contact, "sessions.payerOpened.payerContact"),
         payerDestinationUrl: requireNullableString(body.payer_destination_url, "sessions.payerOpened.payerDestinationUrl"),
         providerCheckoutSessionId: requireNullableString(body.provider_checkout_session_id, "sessions.payerOpened.providerCheckoutSessionId"),
         providerCheckoutSessionPsp: requireNullableString(body.provider_checkout_session_psp, "sessions.payerOpened.providerCheckoutSessionPsp"),
@@ -295,14 +303,14 @@ function toPayerOpenedResult(response) {
         updatedAt: requireString(body.updated_at, "sessions.payerOpened.updatedAt"),
     };
 }
-function requireNullablePayerContact(value, operation = "sessions.retrieve") {
-    if (value === null) {
+function requireNullableContact(value, field) {
+    if (value === null || value === undefined) {
         return null;
     }
-    const contact = requireJsonObject(value, `${operation}.payerContact`);
+    const contact = requireJsonObject(value, field);
     return {
-        email: requireNullableString(contact.email, `${operation}.payerContact.email`),
-        phone: requireNullableString(contact.phone, `${operation}.payerContact.phone`),
+        email: requireNullableString(contact.email, `${field}.email`),
+        phone: requireNullableString(contact.phone, `${field}.phone`),
     };
 }
 function requirePayerHandoffStatus(value) {

package/dist/esm/version.d.ts

@@ -1,3 +1,3 @@
 export declare const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
-export declare const proxyCheckoutServerSdkVersion = "0.0.7";
-export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.7";
+export declare const proxyCheckoutServerSdkVersion = "0.0.8-prx-109.81.1";
+export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.8-prx-109.81.1";

package/dist/esm/version.js

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

package/dist/esm/webhook-handler.d.ts

@@ -40,6 +40,20 @@ export interface ProxyWebhookProvisioningFailure {
     readonly errorMessage: string;
     readonly metadata?: JsonObject;
 }
+/**
+ * Optional data recorded when the handler acknowledges successful initial
+ * provisioning back to Proxy. This is audit/reconciliation data only. It does
+ * not grant access, does not participate in future claim-token validation, and
+ * should not contain secrets.
+ */
+export interface ProxyWebhookProvisioningSuccess {
+    /** Stable merchant-side row id that fulfilled the session, such as a pending entitlement or role id. */
+    readonly fulfillmentReference?: string;
+    /** Small non-secret facts to store on Proxy's provisioned session/audit event. */
+    readonly metadata?: JsonObject;
+}
+type ProxyWebhookNoProvisioningMetadataResult = void;
+export type ProxyWebhookProvisioningSuccessResult = ProxyWebhookProvisioningSuccess | null | undefined | ProxyWebhookNoProvisioningMetadataResult;
 export interface ProxyWebhookPayloadInput {
     readonly body: Buffer | string;
     readonly signature?: string | null;
@@ -56,8 +70,14 @@ export interface ProxyWebhookHandlerOptions {
      * failure payload only after the merchant knows retrying cannot grant access.
      */
     readonly classifyProvisioningFailure?: (error: unknown, resolved: ResolvedProxyEvent) => Promise<ProxyWebhookProvisioningFailure | null | undefined> | ProxyWebhookProvisioningFailure | null | undefined;
-    /** Merchant entitlement callback, invoked once per claimed event after current-state resolution. */
-    readonly onResolved: (resolved: ResolvedProxyEvent) => Promise<void> | void;
+    /**
+     * Merchant entitlement callback, invoked once per claimed event after
+     * current-state resolution. For initial provisioning, mutate the merchant's
+     * entitlement store first, then optionally return the merchant-side row id
+     * and non-secret metadata to record on Proxy's provisioned acknowledgement.
+     * Do not return claim tokens or other secrets here.
+     */
+    readonly onResolved: (resolved: ResolvedProxyEvent) => Promise<ProxyWebhookProvisioningSuccessResult> | ProxyWebhookProvisioningSuccessResult;
     /** Optional request id forwarded to the current-state retrieval calls. */
     readonly requestId?: string;
     /** Endpoint signing secret. */
@@ -102,3 +122,4 @@ export declare class ProxyWebhooksResource {
     private runResolvedHandler;
     private requireSessionsResource;
 }
+export {};

package/dist/esm/webhook-handler.js

@@ -61,9 +61,11 @@ export class ProxyWebhooksResource {
         let resolved;
         try {
             resolved = await this.events.resolveCurrentState(event, { requestId: options.requestId });
-            const provisioningFailed = await this.runResolvedHandler(resolved, options);
-            if (!provisioningFailed && resolved.kind === "initial_provision") {
+            const provisioning = await this.runResolvedHandler(resolved, options);
+            if (!provisioning.failed && resolved.kind === "initial_provision") {
                 await this.requireSessionsResource("mark provisioned").markProvisioned(resolved.session.id, {
+                    fulfillmentReference: provisioning.success?.fulfillmentReference,
+                    metadata: provisioning.success?.metadata,
                     requestId: options.requestId,
                 });
             }
@@ -127,8 +129,11 @@ export class ProxyWebhooksResource {
     }
     async runResolvedHandler(resolved, options) {
         try {
-            await options.onResolved(resolved);
-            return false;
+            const success = await options.onResolved(resolved);
+            return {
+                failed: false,
+                success: normalizeProvisioningSuccess(success),
+            };
         }
         catch (error) {
             if (resolved.kind !== "initial_provision" || !options.classifyProvisioningFailure) {
@@ -144,7 +149,7 @@ export class ProxyWebhooksResource {
                 metadata: failure.metadata,
                 requestId: options.requestId,
             });
-            return true;
+            return { failed: true };
         }
     }
     requireSessionsResource(operation) {
@@ -156,6 +161,21 @@ export class ProxyWebhooksResource {
         });
     }
 }
+function normalizeProvisioningSuccess(value) {
+    if (value == null) {
+        return undefined;
+    }
+    const success = {};
+    if (value.fulfillmentReference !== undefined) {
+        success.fulfillmentReference = value.fulfillmentReference;
+    }
+    if (value.metadata !== undefined) {
+        success.metadata = value.metadata;
+    }
+    return success.fulfillmentReference === undefined && success.metadata === undefined
+        ? undefined
+        : success;
+}
 function toWebhookResponse(result) {
     const headers = { "content-type": "application/json" };
     if (result.retryable) {

package/package.json

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