@proxy-checkout/server-js 0.0.4 → 0.0.5-prx-93.45.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -41,6 +41,9 @@ const handoff = await proxy.sessions.createHandoff({
41
41
  items: [{ product_id: "prod_123", quantity: 1 }],
42
42
  },
43
43
  idempotencyKey: "order_123",
44
+ // Optional: omit in normal production flows to use the dashboard default.
45
+ // Preview/staging/multi-origin environments may override the merchant payer page.
46
+ payerDestinationUrl: "https://preview.example.com/checkout",
44
47
  });
45
48
 
46
49
  console.log(handoff.handoffUrl);
@@ -79,6 +82,14 @@ if (event.type === "subscription.renewed") {
79
82
  Production calls default to `https://api.proxycheckout.com`. Tests, local
80
83
  development, and previews can pass `apiHost`.
81
84
 
85
+ Configure a production/default payer destination and allowed hosts in the Proxy
86
+ dashboard. `payerDestinationUrl` is optional. Most production integrations can
87
+ omit it and use the dashboard default. Preview, staging, or multi-origin
88
+ environments may pass `payerDestinationUrl` to `sessions.createHandoff(...)`;
89
+ Proxy validates the host against the configured allowed hosts, stores the
90
+ destination on the handoff session, and forwards the payer there when the hosted
91
+ handoff opens.
92
+
82
93
  ## First Publish Decisions
83
94
 
84
95
  The first public package versions are intentionally `0.0.x` because the SDK API is
@@ -31,7 +31,7 @@ class ProxyCheckoutServerClient {
31
31
  });
32
32
  this.subscriptions = new subscriptions_js_1.ProxySubscriptionsResource(httpClient, this.sessions);
33
33
  this.events = new events_js_1.ProxyEventsResource(this.sessions, this.subscriptions);
34
- this.webhooks = new webhook_handler_js_1.ProxyWebhooksResource(this.events);
34
+ this.webhooks = new webhook_handler_js_1.ProxyWebhooksResource(this.events, this.sessions);
35
35
  this.webhookEndpoints = new webhooks_js_1.ProxyWebhookEndpointsResource(httpClient);
36
36
  }
37
37
  }
@@ -4,10 +4,10 @@ export { assertCartBuyerReference, assertSubscriptionMatchesSession, } from "./c
4
4
  export { ProxyCheckoutApiError, type ProxyCheckoutApiErrorDetails, type ProxyCheckoutValidationCode, ProxyCheckoutValidationError, } from "./errors.js";
5
5
  export { ProxyEventsResource, type ResolvedIgnored, type ResolvedInitialProvision, type ResolvedPaymentAttempt, type ResolvedPaymentRisk, type ResolvedProxyEvent, type ResolvedProxyEventKind, type ResolvedSubscriptionCancelled, type ResolvedSubscriptionCancelScheduled, type ResolvedSubscriptionRenewed, type ResolvedTerminalSession, type ResolveProxyEventOptions, } from "./events.js";
6
6
  export { AT_RISK_SUBSCRIPTION_STATUSES, ENDED_SUBSCRIPTION_STATUSES, isSessionProvisionable, isSessionTerminal, isSubscriptionEnded, isSubscriptionPaymentAtRisk, PROVISIONABLE_SESSION_STATUSES, parseOptionalProxyDate, requireProxyDate, subscriptionAccessEndsAt, subscriptionWillRenew, TERMINAL_SESSION_STATUSES, } from "./lifecycle.js";
7
- export { type CreateProxySessionHandoffInput, type CreateProxySessionInput, type CreateProxySessionOptions, type MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, type ProxySessionProviderBinding, ProxySessionsResource, proxyCheckoutServerEndpoints, type RecordProviderBindingInput, type SetProxySessionCartInput, type TypedMerchantProxySession, } from "./sessions.js";
7
+ export { type CreateProxySessionHandoffInput, type CreateProxySessionInput, type CreateProxySessionOptions, type MarkProxySessionProvisionedInput, type MarkProxySessionProvisioningFailedInput, type MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, type ProxySessionProviderBinding, type ProxySessionProvisioningAcknowledgement, ProxySessionsResource, proxyCheckoutServerEndpoints, type RecordProviderBindingInput, type SetProxySessionCartInput, type TypedMerchantProxySession, } from "./sessions.js";
8
8
  export { type MerchantProxySubscription, ProxySubscriptionsResource, type ProxySubscriptionWithSession, type ProxySubscriptionWithUntypedSession, proxyCheckoutSubscriptionEndpoints, } from "./subscriptions.js";
9
9
  export type { JsonObject, JsonPrimitive, JsonValue, ProxyCheckoutFetch, ProxyCheckoutServerClientOptions, ProxyCheckoutServerRequestOptions, } from "./types.js";
10
10
  export { proxyCheckoutServerSdkName, proxyCheckoutServerSdkUserAgent, proxyCheckoutServerSdkVersion, } from "./version.js";
11
11
  export { isProxyPaymentAttemptEvent, isProxySessionEvent, isProxySubscriptionEvent, PROXY_WEBHOOK_EVENT_TYPES, type ProxyWebhookEventType, } from "./webhook-events.js";
12
- export { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, type ProxyWebhookClaimResult, type ProxyWebhookHandlerOptions, type ProxyWebhookOutcome, type ProxyWebhookPayloadInput, type ProxyWebhookProcessRecord, type ProxyWebhookProcessResult, type ProxyWebhookRequestInput, type ProxyWebhookStore, ProxyWebhooksResource, } from "./webhook-handler.js";
12
+ 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";
13
13
  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";
@@ -4,10 +4,10 @@ export { assertCartBuyerReference, assertSubscriptionMatchesSession, } from "./c
4
4
  export { ProxyCheckoutApiError, type ProxyCheckoutApiErrorDetails, type ProxyCheckoutValidationCode, ProxyCheckoutValidationError, } from "./errors.js";
5
5
  export { ProxyEventsResource, type ResolvedIgnored, type ResolvedInitialProvision, type ResolvedPaymentAttempt, type ResolvedPaymentRisk, type ResolvedProxyEvent, type ResolvedProxyEventKind, type ResolvedSubscriptionCancelled, type ResolvedSubscriptionCancelScheduled, type ResolvedSubscriptionRenewed, type ResolvedTerminalSession, type ResolveProxyEventOptions, } from "./events.js";
6
6
  export { AT_RISK_SUBSCRIPTION_STATUSES, ENDED_SUBSCRIPTION_STATUSES, isSessionProvisionable, isSessionTerminal, isSubscriptionEnded, isSubscriptionPaymentAtRisk, PROVISIONABLE_SESSION_STATUSES, parseOptionalProxyDate, requireProxyDate, subscriptionAccessEndsAt, subscriptionWillRenew, TERMINAL_SESSION_STATUSES, } from "./lifecycle.js";
7
- export { type CreateProxySessionHandoffInput, type CreateProxySessionInput, type CreateProxySessionOptions, type MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, type ProxySessionProviderBinding, ProxySessionsResource, proxyCheckoutServerEndpoints, type RecordProviderBindingInput, type SetProxySessionCartInput, type TypedMerchantProxySession, } from "./sessions.js";
7
+ export { type CreateProxySessionHandoffInput, type CreateProxySessionInput, type CreateProxySessionOptions, type MarkProxySessionProvisionedInput, type MarkProxySessionProvisioningFailedInput, type MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, type ProxySessionProviderBinding, type ProxySessionProvisioningAcknowledgement, ProxySessionsResource, proxyCheckoutServerEndpoints, type RecordProviderBindingInput, type SetProxySessionCartInput, type TypedMerchantProxySession, } from "./sessions.js";
8
8
  export { type MerchantProxySubscription, ProxySubscriptionsResource, type ProxySubscriptionWithSession, type ProxySubscriptionWithUntypedSession, proxyCheckoutSubscriptionEndpoints, } from "./subscriptions.js";
9
9
  export type { JsonObject, JsonPrimitive, JsonValue, ProxyCheckoutFetch, ProxyCheckoutServerClientOptions, ProxyCheckoutServerRequestOptions, } from "./types.js";
10
10
  export { proxyCheckoutServerSdkName, proxyCheckoutServerSdkUserAgent, proxyCheckoutServerSdkVersion, } from "./version.js";
11
11
  export { isProxyPaymentAttemptEvent, isProxySessionEvent, isProxySubscriptionEvent, PROXY_WEBHOOK_EVENT_TYPES, type ProxyWebhookEventType, } from "./webhook-events.js";
12
- export { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, type ProxyWebhookClaimResult, type ProxyWebhookHandlerOptions, type ProxyWebhookOutcome, type ProxyWebhookPayloadInput, type ProxyWebhookProcessRecord, type ProxyWebhookProcessResult, type ProxyWebhookRequestInput, type ProxyWebhookStore, ProxyWebhooksResource, } from "./webhook-handler.js";
12
+ 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";
13
13
  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";
@@ -18,6 +18,7 @@ export interface CreateProxySessionInput extends CreateProxySessionOptions {
18
18
  };
19
19
  }
20
20
  export interface CreateProxySessionHandoffInput extends CreateProxySessionInput {
21
+ readonly payerDestinationUrl?: string;
21
22
  readonly payHost?: string;
22
23
  readonly publishableKey?: string;
23
24
  }
@@ -47,6 +48,7 @@ export interface MerchantProxySession {
47
48
  readonly email: string | null;
48
49
  readonly phone: string | null;
49
50
  } | null;
51
+ readonly payerDestinationUrl: string | null;
50
52
  readonly providerCheckoutSessionId: string | null;
51
53
  readonly providerCheckoutSessionPsp: string | null;
52
54
  readonly status: string;
@@ -84,6 +86,20 @@ export interface ProxySessionProviderBinding {
84
86
  readonly psp: string;
85
87
  readonly updatedAt: string;
86
88
  }
89
+ export interface MarkProxySessionProvisionedInput extends ProxyCheckoutServerRequestOptions {
90
+ readonly fulfillmentReference?: string;
91
+ readonly metadata?: JsonObject;
92
+ }
93
+ export interface MarkProxySessionProvisioningFailedInput extends ProxyCheckoutServerRequestOptions {
94
+ readonly errorCode?: string;
95
+ readonly errorMessage: string;
96
+ readonly metadata?: JsonObject;
97
+ }
98
+ export interface ProxySessionProvisioningAcknowledgement {
99
+ readonly proxySessionId: string;
100
+ readonly status: "provisioned" | "provisioning_failed";
101
+ readonly updatedAt: string;
102
+ }
87
103
  export declare const proxyCheckoutServerEndpoints: readonly [{
88
104
  readonly method: "POST";
89
105
  readonly operation: "sessions.create";
@@ -112,6 +128,14 @@ export declare const proxyCheckoutServerEndpoints: readonly [{
112
128
  readonly method: "POST";
113
129
  readonly operation: "sessions.providerBindings.create";
114
130
  readonly path: "/proxy_sessions/:id/provider_bindings";
131
+ }, {
132
+ readonly method: "POST";
133
+ readonly operation: "sessions.markProvisioned";
134
+ readonly path: "/proxy_sessions/:id/provisioned";
135
+ }, {
136
+ readonly method: "POST";
137
+ readonly operation: "sessions.markProvisioningFailed";
138
+ readonly path: "/proxy_sessions/:id/provisioning_failed";
115
139
  }];
116
140
  export declare class ProxySessionsResource {
117
141
  private readonly httpClient;
@@ -144,6 +168,8 @@ export declare class ProxySessionsResource {
144
168
  * the session is already bound to a different one.
145
169
  */
146
170
  recordProviderBinding(proxySessionId: string, input: RecordProviderBindingInput): Promise<ProxySessionProviderBinding>;
171
+ markProvisioned(proxySessionId: string, input?: MarkProxySessionProvisionedInput): Promise<ProxySessionProvisioningAcknowledgement>;
172
+ markProvisioningFailed(proxySessionId: string, input: MarkProxySessionProvisioningFailedInput): Promise<ProxySessionProvisioningAcknowledgement>;
147
173
  }
148
174
  export declare class ProxySessionCartResource {
149
175
  private readonly httpClient;
@@ -18,6 +18,7 @@ export interface CreateProxySessionInput extends CreateProxySessionOptions {
18
18
  };
19
19
  }
20
20
  export interface CreateProxySessionHandoffInput extends CreateProxySessionInput {
21
+ readonly payerDestinationUrl?: string;
21
22
  readonly payHost?: string;
22
23
  readonly publishableKey?: string;
23
24
  }
@@ -47,6 +48,7 @@ export interface MerchantProxySession {
47
48
  readonly email: string | null;
48
49
  readonly phone: string | null;
49
50
  } | null;
51
+ readonly payerDestinationUrl: string | null;
50
52
  readonly providerCheckoutSessionId: string | null;
51
53
  readonly providerCheckoutSessionPsp: string | null;
52
54
  readonly status: string;
@@ -84,6 +86,20 @@ export interface ProxySessionProviderBinding {
84
86
  readonly psp: string;
85
87
  readonly updatedAt: string;
86
88
  }
89
+ export interface MarkProxySessionProvisionedInput extends ProxyCheckoutServerRequestOptions {
90
+ readonly fulfillmentReference?: string;
91
+ readonly metadata?: JsonObject;
92
+ }
93
+ export interface MarkProxySessionProvisioningFailedInput extends ProxyCheckoutServerRequestOptions {
94
+ readonly errorCode?: string;
95
+ readonly errorMessage: string;
96
+ readonly metadata?: JsonObject;
97
+ }
98
+ export interface ProxySessionProvisioningAcknowledgement {
99
+ readonly proxySessionId: string;
100
+ readonly status: "provisioned" | "provisioning_failed";
101
+ readonly updatedAt: string;
102
+ }
87
103
  export declare const proxyCheckoutServerEndpoints: readonly [{
88
104
  readonly method: "POST";
89
105
  readonly operation: "sessions.create";
@@ -112,6 +128,14 @@ export declare const proxyCheckoutServerEndpoints: readonly [{
112
128
  readonly method: "POST";
113
129
  readonly operation: "sessions.providerBindings.create";
114
130
  readonly path: "/proxy_sessions/:id/provider_bindings";
131
+ }, {
132
+ readonly method: "POST";
133
+ readonly operation: "sessions.markProvisioned";
134
+ readonly path: "/proxy_sessions/:id/provisioned";
135
+ }, {
136
+ readonly method: "POST";
137
+ readonly operation: "sessions.markProvisioningFailed";
138
+ readonly path: "/proxy_sessions/:id/provisioning_failed";
115
139
  }];
116
140
  export declare class ProxySessionsResource {
117
141
  private readonly httpClient;
@@ -144,6 +168,8 @@ export declare class ProxySessionsResource {
144
168
  * the session is already bound to a different one.
145
169
  */
146
170
  recordProviderBinding(proxySessionId: string, input: RecordProviderBindingInput): Promise<ProxySessionProviderBinding>;
171
+ markProvisioned(proxySessionId: string, input?: MarkProxySessionProvisionedInput): Promise<ProxySessionProvisioningAcknowledgement>;
172
+ markProvisioningFailed(proxySessionId: string, input: MarkProxySessionProvisioningFailedInput): Promise<ProxySessionProvisioningAcknowledgement>;
147
173
  }
148
174
  export declare class ProxySessionCartResource {
149
175
  private readonly httpClient;
@@ -40,6 +40,16 @@ exports.proxyCheckoutServerEndpoints = [
40
40
  operation: "sessions.providerBindings.create",
41
41
  path: "/proxy_sessions/:id/provider_bindings",
42
42
  },
43
+ {
44
+ method: "POST",
45
+ operation: "sessions.markProvisioned",
46
+ path: "/proxy_sessions/:id/provisioned",
47
+ },
48
+ {
49
+ method: "POST",
50
+ operation: "sessions.markProvisioningFailed",
51
+ path: "/proxy_sessions/:id/provisioning_failed",
52
+ },
43
53
  ];
44
54
  class ProxySessionsResource {
45
55
  httpClient;
@@ -68,6 +78,9 @@ class ProxySessionsResource {
68
78
  }
69
79
  const response = await this.httpClient.request("POST", "/proxy_sessions/handoff", {
70
80
  ...toCreateProxySessionBody(input),
81
+ ...(input.payerDestinationUrl !== undefined
82
+ ? { payer_destination_url: input.payerDestinationUrl }
83
+ : {}),
71
84
  publishable_key: publishableKey,
72
85
  }, {
73
86
  idempotencyKey: input.idempotencyKey,
@@ -137,6 +150,21 @@ class ProxySessionsResource {
137
150
  updatedAt: (0, response_validators_js_1.requireString)(body.updated_at, "sessions.providerBindings.create.updatedAt"),
138
151
  };
139
152
  }
153
+ async markProvisioned(proxySessionId, input = {}) {
154
+ const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/provisioned`, removeUndefinedValues({
155
+ fulfillment_reference: input.fulfillmentReference,
156
+ metadata: input.metadata,
157
+ }), { requestId: input.requestId });
158
+ return toProvisioningAcknowledgement(response, "sessions.markProvisioned");
159
+ }
160
+ async markProvisioningFailed(proxySessionId, input) {
161
+ const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/provisioning_failed`, removeUndefinedValues({
162
+ error_code: input.errorCode,
163
+ error_message: input.errorMessage,
164
+ metadata: input.metadata,
165
+ }), { requestId: input.requestId });
166
+ return toProvisioningAcknowledgement(response, "sessions.markProvisioningFailed");
167
+ }
140
168
  }
141
169
  exports.ProxySessionsResource = ProxySessionsResource;
142
170
  class ProxySessionCartResource {
@@ -232,6 +260,7 @@ function toMerchantProxySession(response) {
232
260
  integrationMode: (0, response_validators_js_1.requireString)(body.integration_mode, "sessions.retrieve.integrationMode"),
233
261
  metadata: (0, response_validators_js_1.requireJsonObject)(body.metadata, "sessions.retrieve.metadata"),
234
262
  payerContact: requireNullablePayerContact(body.payer_contact),
263
+ payerDestinationUrl: (0, response_validators_js_1.requireNullableString)(body.payer_destination_url, "sessions.retrieve.payerDestinationUrl"),
235
264
  providerCheckoutSessionId: (0, response_validators_js_1.requireNullableString)(body.provider_checkout_session_id, "sessions.retrieve.providerCheckoutSessionId"),
236
265
  providerCheckoutSessionPsp: (0, response_validators_js_1.requireNullableString)(body.provider_checkout_session_psp, "sessions.retrieve.providerCheckoutSessionPsp"),
237
266
  status: (0, response_validators_js_1.requireString)(body.status, "sessions.retrieve.status"),
@@ -257,6 +286,7 @@ function toPayerOpenedResult(response) {
257
286
  integrationMode: (0, response_validators_js_1.requireString)(body.integration_mode, "sessions.payerOpened.integrationMode"),
258
287
  metadata: (0, response_validators_js_1.requireJsonObject)(body.metadata, "sessions.payerOpened.metadata"),
259
288
  payerContact: requireNullablePayerContact(body.payer_contact, "sessions.payerOpened"),
289
+ payerDestinationUrl: (0, response_validators_js_1.requireNullableString)(body.payer_destination_url, "sessions.payerOpened.payerDestinationUrl"),
260
290
  providerCheckoutSessionId: (0, response_validators_js_1.requireNullableString)(body.provider_checkout_session_id, "sessions.payerOpened.providerCheckoutSessionId"),
261
291
  providerCheckoutSessionPsp: (0, response_validators_js_1.requireNullableString)(body.provider_checkout_session_psp, "sessions.payerOpened.providerCheckoutSessionPsp"),
262
292
  status,
@@ -280,6 +310,18 @@ function requirePayerHandoffStatus(value) {
280
310
  }
281
311
  throw new Error("Proxy API response field sessions.payerHandoff.status is unsupported.");
282
312
  }
313
+ function toProvisioningAcknowledgement(response, operation) {
314
+ const body = (0, response_validators_js_1.requireJsonObject)(response, operation);
315
+ const status = (0, response_validators_js_1.requireString)(body.status, `${operation}.status`);
316
+ if (status !== "provisioned" && status !== "provisioning_failed") {
317
+ throw new Error(`Proxy API response field ${operation}.status is unsupported.`);
318
+ }
319
+ return {
320
+ proxySessionId: (0, response_validators_js_1.requireString)(body.proxy_session_id, `${operation}.proxySessionId`),
321
+ status,
322
+ updatedAt: (0, response_validators_js_1.requireString)(body.updated_at, `${operation}.updatedAt`),
323
+ };
324
+ }
283
325
  function buildHandoffUrl({ payHost, proxySessionId, publishableKey, }) {
284
326
  const url = new URL(`${normalizePayHost(payHost)}/s/${encodeURIComponent(proxySessionId)}`);
285
327
  url.searchParams.set("pk", publishableKey);
@@ -1,3 +1,3 @@
1
1
  export declare const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
2
- export declare const proxyCheckoutServerSdkVersion = "0.0.4";
3
- export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.4";
2
+ export declare const proxyCheckoutServerSdkVersion = "0.0.5-prx-93.45.1";
3
+ export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.5-prx-93.45.1";
@@ -1,3 +1,3 @@
1
1
  export declare const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
2
- export declare const proxyCheckoutServerSdkVersion = "0.0.4";
3
- export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.4";
2
+ export declare const proxyCheckoutServerSdkVersion = "0.0.5-prx-93.45.1";
3
+ export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.5-prx-93.45.1";
@@ -2,5 +2,5 @@
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.proxyCheckoutServerSdkUserAgent = exports.proxyCheckoutServerSdkVersion = exports.proxyCheckoutServerSdkName = void 0;
4
4
  exports.proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
5
- exports.proxyCheckoutServerSdkVersion = "0.0.4";
5
+ exports.proxyCheckoutServerSdkVersion = "0.0.5-prx-93.45.1";
6
6
  exports.proxyCheckoutServerSdkUserAgent = `${exports.proxyCheckoutServerSdkName}/${exports.proxyCheckoutServerSdkVersion}`;
@@ -8,6 +8,8 @@
8
8
  * current-state retrieval so customer webhook routes stay tiny.
9
9
  */
10
10
  import type { ProxyEventsResource, ResolvedProxyEvent, ResolvedProxyEventKind } from "./events.js";
11
+ import type { ProxySessionsResource } from "./sessions.js";
12
+ import type { JsonObject } from "./types.js";
11
13
  import { type ProxyWebhookEvent } from "./webhooks.js";
12
14
  /** Seconds advertised in `Retry-After` when an event is already in flight. */
13
15
  export declare const PROXY_WEBHOOK_RETRY_AFTER_SECONDS = 30;
@@ -33,6 +35,11 @@ export interface ProxyWebhookStore {
33
35
  /** Mark a claimed event processed (idempotency commit). */
34
36
  markProcessed(eventId: string, record: ProxyWebhookProcessRecord): Promise<void> | void;
35
37
  }
38
+ export interface ProxyWebhookProvisioningFailure {
39
+ readonly errorCode?: string;
40
+ readonly errorMessage: string;
41
+ readonly metadata?: JsonObject;
42
+ }
36
43
  export interface ProxyWebhookPayloadInput {
37
44
  readonly body: Buffer | string;
38
45
  readonly signature?: string | null;
@@ -44,6 +51,11 @@ export interface ProxyWebhookPayloadInput {
44
51
  */
45
52
  export type ProxyWebhookRequestInput = ProxyWebhookPayloadInput | Request;
46
53
  export interface ProxyWebhookHandlerOptions {
54
+ /**
55
+ * Optional classifier for non-retryable initial-provision failures. Return a
56
+ * failure payload only after the merchant knows retrying cannot grant access.
57
+ */
58
+ readonly classifyProvisioningFailure?: (error: unknown, resolved: ResolvedProxyEvent) => Promise<ProxyWebhookProvisioningFailure | null | undefined> | ProxyWebhookProvisioningFailure | null | undefined;
47
59
  /** Merchant entitlement callback, invoked once per claimed event after current-state resolution. */
48
60
  readonly onResolved: (resolved: ResolvedProxyEvent) => Promise<void> | void;
49
61
  /** Optional request id forwarded to the current-state retrieval calls. */
@@ -64,7 +76,8 @@ export interface ProxyWebhookProcessResult {
64
76
  }
65
77
  export declare class ProxyWebhooksResource {
66
78
  private readonly events;
67
- constructor(events: ProxyEventsResource);
79
+ private readonly sessions;
80
+ constructor(events: ProxyEventsResource, sessions: Pick<ProxySessionsResource, "markProvisioned" | "markProvisioningFailed">);
68
81
  /** Low-level: verify + construct the event without resolving lifecycle. */
69
82
  constructEvent(input: {
70
83
  body: Buffer | string;
@@ -86,4 +99,5 @@ export declare class ProxyWebhooksResource {
86
99
  * surface a 500 and Proxy retries.
87
100
  */
88
101
  handle(input: ProxyWebhookRequestInput, options: ProxyWebhookHandlerOptions): Promise<Response>;
102
+ private runResolvedHandler;
89
103
  }
@@ -8,6 +8,8 @@
8
8
  * current-state retrieval so customer webhook routes stay tiny.
9
9
  */
10
10
  import type { ProxyEventsResource, ResolvedProxyEvent, ResolvedProxyEventKind } from "./events.js";
11
+ import type { ProxySessionsResource } from "./sessions.js";
12
+ import type { JsonObject } from "./types.js";
11
13
  import { type ProxyWebhookEvent } from "./webhooks.js";
12
14
  /** Seconds advertised in `Retry-After` when an event is already in flight. */
13
15
  export declare const PROXY_WEBHOOK_RETRY_AFTER_SECONDS = 30;
@@ -33,6 +35,11 @@ export interface ProxyWebhookStore {
33
35
  /** Mark a claimed event processed (idempotency commit). */
34
36
  markProcessed(eventId: string, record: ProxyWebhookProcessRecord): Promise<void> | void;
35
37
  }
38
+ export interface ProxyWebhookProvisioningFailure {
39
+ readonly errorCode?: string;
40
+ readonly errorMessage: string;
41
+ readonly metadata?: JsonObject;
42
+ }
36
43
  export interface ProxyWebhookPayloadInput {
37
44
  readonly body: Buffer | string;
38
45
  readonly signature?: string | null;
@@ -44,6 +51,11 @@ export interface ProxyWebhookPayloadInput {
44
51
  */
45
52
  export type ProxyWebhookRequestInput = ProxyWebhookPayloadInput | Request;
46
53
  export interface ProxyWebhookHandlerOptions {
54
+ /**
55
+ * Optional classifier for non-retryable initial-provision failures. Return a
56
+ * failure payload only after the merchant knows retrying cannot grant access.
57
+ */
58
+ readonly classifyProvisioningFailure?: (error: unknown, resolved: ResolvedProxyEvent) => Promise<ProxyWebhookProvisioningFailure | null | undefined> | ProxyWebhookProvisioningFailure | null | undefined;
47
59
  /** Merchant entitlement callback, invoked once per claimed event after current-state resolution. */
48
60
  readonly onResolved: (resolved: ResolvedProxyEvent) => Promise<void> | void;
49
61
  /** Optional request id forwarded to the current-state retrieval calls. */
@@ -64,7 +76,8 @@ export interface ProxyWebhookProcessResult {
64
76
  }
65
77
  export declare class ProxyWebhooksResource {
66
78
  private readonly events;
67
- constructor(events: ProxyEventsResource);
79
+ private readonly sessions;
80
+ constructor(events: ProxyEventsResource, sessions: Pick<ProxySessionsResource, "markProvisioned" | "markProvisioningFailed">);
68
81
  /** Low-level: verify + construct the event without resolving lifecycle. */
69
82
  constructEvent(input: {
70
83
  body: Buffer | string;
@@ -86,4 +99,5 @@ export declare class ProxyWebhooksResource {
86
99
  * surface a 500 and Proxy retries.
87
100
  */
88
101
  handle(input: ProxyWebhookRequestInput, options: ProxyWebhookHandlerOptions): Promise<Response>;
102
+ private runResolvedHandler;
89
103
  }
@@ -15,8 +15,10 @@ const webhooks_js_1 = require("./webhooks.js");
15
15
  exports.PROXY_WEBHOOK_RETRY_AFTER_SECONDS = 30;
16
16
  class ProxyWebhooksResource {
17
17
  events;
18
- constructor(events) {
18
+ sessions;
19
+ constructor(events, sessions) {
19
20
  this.events = events;
21
+ this.sessions = sessions;
20
22
  }
21
23
  /** Low-level: verify + construct the event without resolving lifecycle. */
22
24
  constructEvent(input) {
@@ -61,7 +63,12 @@ class ProxyWebhooksResource {
61
63
  let resolved;
62
64
  try {
63
65
  resolved = await this.events.resolveCurrentState(event, { requestId: options.requestId });
64
- await options.onResolved(resolved);
66
+ const provisioningFailed = await this.runResolvedHandler(resolved, options);
67
+ if (!provisioningFailed && resolved.kind === "initial_provision") {
68
+ await this.sessions.markProvisioned(resolved.session.id, {
69
+ requestId: options.requestId,
70
+ });
71
+ }
65
72
  }
66
73
  catch (error) {
67
74
  if (store !== undefined) {
@@ -120,6 +127,28 @@ class ProxyWebhooksResource {
120
127
  }
121
128
  return toWebhookResponse(result);
122
129
  }
130
+ async runResolvedHandler(resolved, options) {
131
+ try {
132
+ await options.onResolved(resolved);
133
+ return false;
134
+ }
135
+ catch (error) {
136
+ if (resolved.kind !== "initial_provision" || !options.classifyProvisioningFailure) {
137
+ throw error;
138
+ }
139
+ const failure = await options.classifyProvisioningFailure(error, resolved);
140
+ if (!failure) {
141
+ throw error;
142
+ }
143
+ await this.sessions.markProvisioningFailed(resolved.session.id, {
144
+ errorCode: failure.errorCode,
145
+ errorMessage: failure.errorMessage,
146
+ metadata: failure.metadata,
147
+ requestId: options.requestId,
148
+ });
149
+ return true;
150
+ }
151
+ }
123
152
  }
124
153
  exports.ProxyWebhooksResource = ProxyWebhooksResource;
125
154
  function toWebhookResponse(result) {
@@ -27,7 +27,7 @@ export class ProxyCheckoutServerClient {
27
27
  });
28
28
  this.subscriptions = new ProxySubscriptionsResource(httpClient, this.sessions);
29
29
  this.events = new ProxyEventsResource(this.sessions, this.subscriptions);
30
- this.webhooks = new ProxyWebhooksResource(this.events);
30
+ this.webhooks = new ProxyWebhooksResource(this.events, this.sessions);
31
31
  this.webhookEndpoints = new ProxyWebhookEndpointsResource(httpClient);
32
32
  }
33
33
  }
@@ -4,10 +4,10 @@ export { assertCartBuyerReference, assertSubscriptionMatchesSession, } from "./c
4
4
  export { ProxyCheckoutApiError, type ProxyCheckoutApiErrorDetails, type ProxyCheckoutValidationCode, ProxyCheckoutValidationError, } from "./errors.js";
5
5
  export { ProxyEventsResource, type ResolvedIgnored, type ResolvedInitialProvision, type ResolvedPaymentAttempt, type ResolvedPaymentRisk, type ResolvedProxyEvent, type ResolvedProxyEventKind, type ResolvedSubscriptionCancelled, type ResolvedSubscriptionCancelScheduled, type ResolvedSubscriptionRenewed, type ResolvedTerminalSession, type ResolveProxyEventOptions, } from "./events.js";
6
6
  export { AT_RISK_SUBSCRIPTION_STATUSES, ENDED_SUBSCRIPTION_STATUSES, isSessionProvisionable, isSessionTerminal, isSubscriptionEnded, isSubscriptionPaymentAtRisk, PROVISIONABLE_SESSION_STATUSES, parseOptionalProxyDate, requireProxyDate, subscriptionAccessEndsAt, subscriptionWillRenew, TERMINAL_SESSION_STATUSES, } from "./lifecycle.js";
7
- export { type CreateProxySessionHandoffInput, type CreateProxySessionInput, type CreateProxySessionOptions, type MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, type ProxySessionProviderBinding, ProxySessionsResource, proxyCheckoutServerEndpoints, type RecordProviderBindingInput, type SetProxySessionCartInput, type TypedMerchantProxySession, } from "./sessions.js";
7
+ export { type CreateProxySessionHandoffInput, type CreateProxySessionInput, type CreateProxySessionOptions, type MarkProxySessionProvisionedInput, type MarkProxySessionProvisioningFailedInput, type MerchantProxySession, type PayerHandoffResult, type PayerOpenedResult, type ProxySession, ProxySessionCartResource, type ProxySessionCartResult, type ProxySessionHandoff, type ProxySessionProviderBinding, type ProxySessionProvisioningAcknowledgement, ProxySessionsResource, proxyCheckoutServerEndpoints, type RecordProviderBindingInput, type SetProxySessionCartInput, type TypedMerchantProxySession, } from "./sessions.js";
8
8
  export { type MerchantProxySubscription, ProxySubscriptionsResource, type ProxySubscriptionWithSession, type ProxySubscriptionWithUntypedSession, proxyCheckoutSubscriptionEndpoints, } from "./subscriptions.js";
9
9
  export type { JsonObject, JsonPrimitive, JsonValue, ProxyCheckoutFetch, ProxyCheckoutServerClientOptions, ProxyCheckoutServerRequestOptions, } from "./types.js";
10
10
  export { proxyCheckoutServerSdkName, proxyCheckoutServerSdkUserAgent, proxyCheckoutServerSdkVersion, } from "./version.js";
11
11
  export { isProxyPaymentAttemptEvent, isProxySessionEvent, isProxySubscriptionEvent, PROXY_WEBHOOK_EVENT_TYPES, type ProxyWebhookEventType, } from "./webhook-events.js";
12
- export { PROXY_WEBHOOK_RETRY_AFTER_SECONDS, type ProxyWebhookClaimResult, type ProxyWebhookHandlerOptions, type ProxyWebhookOutcome, type ProxyWebhookPayloadInput, type ProxyWebhookProcessRecord, type ProxyWebhookProcessResult, type ProxyWebhookRequestInput, type ProxyWebhookStore, ProxyWebhooksResource, } from "./webhook-handler.js";
12
+ 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";
13
13
  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";
@@ -18,6 +18,7 @@ export interface CreateProxySessionInput extends CreateProxySessionOptions {
18
18
  };
19
19
  }
20
20
  export interface CreateProxySessionHandoffInput extends CreateProxySessionInput {
21
+ readonly payerDestinationUrl?: string;
21
22
  readonly payHost?: string;
22
23
  readonly publishableKey?: string;
23
24
  }
@@ -47,6 +48,7 @@ export interface MerchantProxySession {
47
48
  readonly email: string | null;
48
49
  readonly phone: string | null;
49
50
  } | null;
51
+ readonly payerDestinationUrl: string | null;
50
52
  readonly providerCheckoutSessionId: string | null;
51
53
  readonly providerCheckoutSessionPsp: string | null;
52
54
  readonly status: string;
@@ -84,6 +86,20 @@ export interface ProxySessionProviderBinding {
84
86
  readonly psp: string;
85
87
  readonly updatedAt: string;
86
88
  }
89
+ export interface MarkProxySessionProvisionedInput extends ProxyCheckoutServerRequestOptions {
90
+ readonly fulfillmentReference?: string;
91
+ readonly metadata?: JsonObject;
92
+ }
93
+ export interface MarkProxySessionProvisioningFailedInput extends ProxyCheckoutServerRequestOptions {
94
+ readonly errorCode?: string;
95
+ readonly errorMessage: string;
96
+ readonly metadata?: JsonObject;
97
+ }
98
+ export interface ProxySessionProvisioningAcknowledgement {
99
+ readonly proxySessionId: string;
100
+ readonly status: "provisioned" | "provisioning_failed";
101
+ readonly updatedAt: string;
102
+ }
87
103
  export declare const proxyCheckoutServerEndpoints: readonly [{
88
104
  readonly method: "POST";
89
105
  readonly operation: "sessions.create";
@@ -112,6 +128,14 @@ export declare const proxyCheckoutServerEndpoints: readonly [{
112
128
  readonly method: "POST";
113
129
  readonly operation: "sessions.providerBindings.create";
114
130
  readonly path: "/proxy_sessions/:id/provider_bindings";
131
+ }, {
132
+ readonly method: "POST";
133
+ readonly operation: "sessions.markProvisioned";
134
+ readonly path: "/proxy_sessions/:id/provisioned";
135
+ }, {
136
+ readonly method: "POST";
137
+ readonly operation: "sessions.markProvisioningFailed";
138
+ readonly path: "/proxy_sessions/:id/provisioning_failed";
115
139
  }];
116
140
  export declare class ProxySessionsResource {
117
141
  private readonly httpClient;
@@ -144,6 +168,8 @@ export declare class ProxySessionsResource {
144
168
  * the session is already bound to a different one.
145
169
  */
146
170
  recordProviderBinding(proxySessionId: string, input: RecordProviderBindingInput): Promise<ProxySessionProviderBinding>;
171
+ markProvisioned(proxySessionId: string, input?: MarkProxySessionProvisionedInput): Promise<ProxySessionProvisioningAcknowledgement>;
172
+ markProvisioningFailed(proxySessionId: string, input: MarkProxySessionProvisioningFailedInput): Promise<ProxySessionProvisioningAcknowledgement>;
147
173
  }
148
174
  export declare class ProxySessionCartResource {
149
175
  private readonly httpClient;
@@ -37,6 +37,16 @@ export const proxyCheckoutServerEndpoints = [
37
37
  operation: "sessions.providerBindings.create",
38
38
  path: "/proxy_sessions/:id/provider_bindings",
39
39
  },
40
+ {
41
+ method: "POST",
42
+ operation: "sessions.markProvisioned",
43
+ path: "/proxy_sessions/:id/provisioned",
44
+ },
45
+ {
46
+ method: "POST",
47
+ operation: "sessions.markProvisioningFailed",
48
+ path: "/proxy_sessions/:id/provisioning_failed",
49
+ },
40
50
  ];
41
51
  export class ProxySessionsResource {
42
52
  httpClient;
@@ -65,6 +75,9 @@ export class ProxySessionsResource {
65
75
  }
66
76
  const response = await this.httpClient.request("POST", "/proxy_sessions/handoff", {
67
77
  ...toCreateProxySessionBody(input),
78
+ ...(input.payerDestinationUrl !== undefined
79
+ ? { payer_destination_url: input.payerDestinationUrl }
80
+ : {}),
68
81
  publishable_key: publishableKey,
69
82
  }, {
70
83
  idempotencyKey: input.idempotencyKey,
@@ -134,6 +147,21 @@ export class ProxySessionsResource {
134
147
  updatedAt: requireString(body.updated_at, "sessions.providerBindings.create.updatedAt"),
135
148
  };
136
149
  }
150
+ async markProvisioned(proxySessionId, input = {}) {
151
+ const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/provisioned`, removeUndefinedValues({
152
+ fulfillment_reference: input.fulfillmentReference,
153
+ metadata: input.metadata,
154
+ }), { requestId: input.requestId });
155
+ return toProvisioningAcknowledgement(response, "sessions.markProvisioned");
156
+ }
157
+ async markProvisioningFailed(proxySessionId, input) {
158
+ const response = await this.httpClient.request("POST", `/proxy_sessions/${encodeURIComponent(proxySessionId)}/provisioning_failed`, removeUndefinedValues({
159
+ error_code: input.errorCode,
160
+ error_message: input.errorMessage,
161
+ metadata: input.metadata,
162
+ }), { requestId: input.requestId });
163
+ return toProvisioningAcknowledgement(response, "sessions.markProvisioningFailed");
164
+ }
137
165
  }
138
166
  export class ProxySessionCartResource {
139
167
  httpClient;
@@ -227,6 +255,7 @@ function toMerchantProxySession(response) {
227
255
  integrationMode: requireString(body.integration_mode, "sessions.retrieve.integrationMode"),
228
256
  metadata: requireJsonObject(body.metadata, "sessions.retrieve.metadata"),
229
257
  payerContact: requireNullablePayerContact(body.payer_contact),
258
+ payerDestinationUrl: requireNullableString(body.payer_destination_url, "sessions.retrieve.payerDestinationUrl"),
230
259
  providerCheckoutSessionId: requireNullableString(body.provider_checkout_session_id, "sessions.retrieve.providerCheckoutSessionId"),
231
260
  providerCheckoutSessionPsp: requireNullableString(body.provider_checkout_session_psp, "sessions.retrieve.providerCheckoutSessionPsp"),
232
261
  status: requireString(body.status, "sessions.retrieve.status"),
@@ -252,6 +281,7 @@ function toPayerOpenedResult(response) {
252
281
  integrationMode: requireString(body.integration_mode, "sessions.payerOpened.integrationMode"),
253
282
  metadata: requireJsonObject(body.metadata, "sessions.payerOpened.metadata"),
254
283
  payerContact: requireNullablePayerContact(body.payer_contact, "sessions.payerOpened"),
284
+ payerDestinationUrl: requireNullableString(body.payer_destination_url, "sessions.payerOpened.payerDestinationUrl"),
255
285
  providerCheckoutSessionId: requireNullableString(body.provider_checkout_session_id, "sessions.payerOpened.providerCheckoutSessionId"),
256
286
  providerCheckoutSessionPsp: requireNullableString(body.provider_checkout_session_psp, "sessions.payerOpened.providerCheckoutSessionPsp"),
257
287
  status,
@@ -275,6 +305,18 @@ function requirePayerHandoffStatus(value) {
275
305
  }
276
306
  throw new Error("Proxy API response field sessions.payerHandoff.status is unsupported.");
277
307
  }
308
+ function toProvisioningAcknowledgement(response, operation) {
309
+ const body = requireJsonObject(response, operation);
310
+ const status = requireString(body.status, `${operation}.status`);
311
+ if (status !== "provisioned" && status !== "provisioning_failed") {
312
+ throw new Error(`Proxy API response field ${operation}.status is unsupported.`);
313
+ }
314
+ return {
315
+ proxySessionId: requireString(body.proxy_session_id, `${operation}.proxySessionId`),
316
+ status,
317
+ updatedAt: requireString(body.updated_at, `${operation}.updatedAt`),
318
+ };
319
+ }
278
320
  function buildHandoffUrl({ payHost, proxySessionId, publishableKey, }) {
279
321
  const url = new URL(`${normalizePayHost(payHost)}/s/${encodeURIComponent(proxySessionId)}`);
280
322
  url.searchParams.set("pk", publishableKey);
@@ -1,3 +1,3 @@
1
1
  export declare const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
2
- export declare const proxyCheckoutServerSdkVersion = "0.0.4";
3
- export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.4";
2
+ export declare const proxyCheckoutServerSdkVersion = "0.0.5-prx-93.45.1";
3
+ export declare const proxyCheckoutServerSdkUserAgent = "@proxy-checkout/server-js/0.0.5-prx-93.45.1";
@@ -1,3 +1,3 @@
1
1
  export const proxyCheckoutServerSdkName = "@proxy-checkout/server-js";
2
- export const proxyCheckoutServerSdkVersion = "0.0.4";
2
+ export const proxyCheckoutServerSdkVersion = "0.0.5-prx-93.45.1";
3
3
  export const proxyCheckoutServerSdkUserAgent = `${proxyCheckoutServerSdkName}/${proxyCheckoutServerSdkVersion}`;
@@ -8,6 +8,8 @@
8
8
  * current-state retrieval so customer webhook routes stay tiny.
9
9
  */
10
10
  import type { ProxyEventsResource, ResolvedProxyEvent, ResolvedProxyEventKind } from "./events.js";
11
+ import type { ProxySessionsResource } from "./sessions.js";
12
+ import type { JsonObject } from "./types.js";
11
13
  import { type ProxyWebhookEvent } from "./webhooks.js";
12
14
  /** Seconds advertised in `Retry-After` when an event is already in flight. */
13
15
  export declare const PROXY_WEBHOOK_RETRY_AFTER_SECONDS = 30;
@@ -33,6 +35,11 @@ export interface ProxyWebhookStore {
33
35
  /** Mark a claimed event processed (idempotency commit). */
34
36
  markProcessed(eventId: string, record: ProxyWebhookProcessRecord): Promise<void> | void;
35
37
  }
38
+ export interface ProxyWebhookProvisioningFailure {
39
+ readonly errorCode?: string;
40
+ readonly errorMessage: string;
41
+ readonly metadata?: JsonObject;
42
+ }
36
43
  export interface ProxyWebhookPayloadInput {
37
44
  readonly body: Buffer | string;
38
45
  readonly signature?: string | null;
@@ -44,6 +51,11 @@ export interface ProxyWebhookPayloadInput {
44
51
  */
45
52
  export type ProxyWebhookRequestInput = ProxyWebhookPayloadInput | Request;
46
53
  export interface ProxyWebhookHandlerOptions {
54
+ /**
55
+ * Optional classifier for non-retryable initial-provision failures. Return a
56
+ * failure payload only after the merchant knows retrying cannot grant access.
57
+ */
58
+ readonly classifyProvisioningFailure?: (error: unknown, resolved: ResolvedProxyEvent) => Promise<ProxyWebhookProvisioningFailure | null | undefined> | ProxyWebhookProvisioningFailure | null | undefined;
47
59
  /** Merchant entitlement callback, invoked once per claimed event after current-state resolution. */
48
60
  readonly onResolved: (resolved: ResolvedProxyEvent) => Promise<void> | void;
49
61
  /** Optional request id forwarded to the current-state retrieval calls. */
@@ -64,7 +76,8 @@ export interface ProxyWebhookProcessResult {
64
76
  }
65
77
  export declare class ProxyWebhooksResource {
66
78
  private readonly events;
67
- constructor(events: ProxyEventsResource);
79
+ private readonly sessions;
80
+ constructor(events: ProxyEventsResource, sessions: Pick<ProxySessionsResource, "markProvisioned" | "markProvisioningFailed">);
68
81
  /** Low-level: verify + construct the event without resolving lifecycle. */
69
82
  constructEvent(input: {
70
83
  body: Buffer | string;
@@ -86,4 +99,5 @@ export declare class ProxyWebhooksResource {
86
99
  * surface a 500 and Proxy retries.
87
100
  */
88
101
  handle(input: ProxyWebhookRequestInput, options: ProxyWebhookHandlerOptions): Promise<Response>;
102
+ private runResolvedHandler;
89
103
  }
@@ -12,8 +12,10 @@ import { constructProxyWebhookEvent, PROXY_SIGNATURE_HEADER, ProxyWebhookSignatu
12
12
  export const PROXY_WEBHOOK_RETRY_AFTER_SECONDS = 30;
13
13
  export class ProxyWebhooksResource {
14
14
  events;
15
- constructor(events) {
15
+ sessions;
16
+ constructor(events, sessions) {
16
17
  this.events = events;
18
+ this.sessions = sessions;
17
19
  }
18
20
  /** Low-level: verify + construct the event without resolving lifecycle. */
19
21
  constructEvent(input) {
@@ -58,7 +60,12 @@ export class ProxyWebhooksResource {
58
60
  let resolved;
59
61
  try {
60
62
  resolved = await this.events.resolveCurrentState(event, { requestId: options.requestId });
61
- await options.onResolved(resolved);
63
+ const provisioningFailed = await this.runResolvedHandler(resolved, options);
64
+ if (!provisioningFailed && resolved.kind === "initial_provision") {
65
+ await this.sessions.markProvisioned(resolved.session.id, {
66
+ requestId: options.requestId,
67
+ });
68
+ }
62
69
  }
63
70
  catch (error) {
64
71
  if (store !== undefined) {
@@ -117,6 +124,28 @@ export class ProxyWebhooksResource {
117
124
  }
118
125
  return toWebhookResponse(result);
119
126
  }
127
+ async runResolvedHandler(resolved, options) {
128
+ try {
129
+ await options.onResolved(resolved);
130
+ return false;
131
+ }
132
+ catch (error) {
133
+ if (resolved.kind !== "initial_provision" || !options.classifyProvisioningFailure) {
134
+ throw error;
135
+ }
136
+ const failure = await options.classifyProvisioningFailure(error, resolved);
137
+ if (!failure) {
138
+ throw error;
139
+ }
140
+ await this.sessions.markProvisioningFailed(resolved.session.id, {
141
+ errorCode: failure.errorCode,
142
+ errorMessage: failure.errorMessage,
143
+ metadata: failure.metadata,
144
+ requestId: options.requestId,
145
+ });
146
+ return true;
147
+ }
148
+ }
120
149
  }
121
150
  function toWebhookResponse(result) {
122
151
  const headers = { "content-type": "application/json" };
package/package.json CHANGED
@@ -7,7 +7,7 @@
7
7
  "sideEffects": false,
8
8
  "type": "module",
9
9
  "types": "./dist/esm/index.d.ts",
10
- "version": "0.0.4",
10
+ "version": "0.0.5-prx-93.45.1",
11
11
  "devDependencies": {
12
12
  "@types/node": "^24.12.4",
13
13
  "@vitest/coverage-v8": "4.1.7",