@proxy-checkout/server-js 0.0.8-prx-109.80.1 → 0.0.8-prx-109.82.1

package/README.md

@@ -39,7 +39,7 @@ const handoff = await proxy.sessions.createHandoff({
   // use a pending entitlement id instead of an email address.
   buyerReference: "buyer_123",
   // Optional beneficiary contact for the person receiving access.
-  beneficiaryContact: { email: "student@example.com" },
+  beneficiaryContact: { email: "recipient@example.com" },
   currency: "usd",
   cartSnapshot: {
     items: [{ product_id: "prod_123", quantity: 1 }],
@@ -93,7 +93,9 @@ await proxy.webhooks.handle(request, {
 });
 ```
 
-For pre-account purchases, create a durable pending entitlement before `sessions.createHandoff(...)`, use that pending entitlement id as `buyerReference`, pass the future student's contact as `beneficiaryContact`, and claim the entitlement after signup/login with your own high-entropy claim token. Treat `proxy_session_id` as public correlation, not as a claim secret.
+`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:
 

package/dist/cjs/sessions.d.cts

@@ -95,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

@@ -95,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/version.d.cts

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

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

@@ -40,11 +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;
 }
-export type ProxyWebhookProvisioningSuccessResult = ProxyWebhookProvisioningSuccess | null | undefined;
+type ProxyWebhookNoProvisioningMetadataResult = void;
+export type ProxyWebhookProvisioningSuccessResult = ProxyWebhookProvisioningSuccess | null | undefined | ProxyWebhookNoProvisioningMetadataResult;
 export interface ProxyWebhookPayloadInput {
     readonly body: Buffer | string;
     readonly signature?: string | null;
@@ -63,8 +72,10 @@ export interface ProxyWebhookHandlerOptions {
     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. For initial provisioning, return a fulfillment
-     * reference and/or metadata to record on Proxy's provisioned acknowledgement.
+     * 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. */
@@ -111,3 +122,4 @@ export declare class ProxyWebhooksResource {
     private runResolvedHandler;
     private requireSessionsResource;
 }
+export {};

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

@@ -40,11 +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;
 }
-export type ProxyWebhookProvisioningSuccessResult = ProxyWebhookProvisioningSuccess | null | undefined;
+type ProxyWebhookNoProvisioningMetadataResult = void;
+export type ProxyWebhookProvisioningSuccessResult = ProxyWebhookProvisioningSuccess | null | undefined | ProxyWebhookNoProvisioningMetadataResult;
 export interface ProxyWebhookPayloadInput {
     readonly body: Buffer | string;
     readonly signature?: string | null;
@@ -63,8 +72,10 @@ export interface ProxyWebhookHandlerOptions {
     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. For initial provisioning, return a fulfillment
-     * reference and/or metadata to record on Proxy's provisioned acknowledgement.
+     * 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. */
@@ -111,3 +122,4 @@ export declare class ProxyWebhooksResource {
     private runResolvedHandler;
     private requireSessionsResource;
 }
+export {};

package/dist/esm/sessions.d.ts

@@ -95,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/version.d.ts

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

package/dist/esm/version.js

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

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

@@ -40,11 +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;
 }
-export type ProxyWebhookProvisioningSuccessResult = ProxyWebhookProvisioningSuccess | null | undefined;
+type ProxyWebhookNoProvisioningMetadataResult = void;
+export type ProxyWebhookProvisioningSuccessResult = ProxyWebhookProvisioningSuccess | null | undefined | ProxyWebhookNoProvisioningMetadataResult;
 export interface ProxyWebhookPayloadInput {
     readonly body: Buffer | string;
     readonly signature?: string | null;
@@ -63,8 +72,10 @@ export interface ProxyWebhookHandlerOptions {
     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. For initial provisioning, return a fulfillment
-     * reference and/or metadata to record on Proxy's provisioned acknowledgement.
+     * 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. */
@@ -111,3 +122,4 @@ export declare class ProxyWebhooksResource {
     private runResolvedHandler;
     private requireSessionsResource;
 }
+export {};

package/package.json

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