@conto_finance/sdk 0.7.0 → 0.7.1

package/README.md

@@ -156,6 +156,11 @@ const confirmed = await conto.checkout.confirm(result.checkpoint, {
   held spend and throws `LinkCardDeniedError`, `LinkCardExpiredError`, `LinkCardTimeoutError`, or
   `LinkWalletUnavailableError`. All extend `LinkCardError`. Do not pay.
 - Retrying with the same input resumes the same checkpoint and Link request.
+- Pass `onLinkApproval` to get Stripe Link's approval page, so a person without the Link app can
+  approve on the web while signed in to Link. It is called once, after Conto approves and Link
+  creates the request, with `{ checkpoint, linkRequestId, approvalUrl, approvalExpiresAt }`.
+  `approvalUrl` is always an HTTPS link.com address. A `LinkCardError` has it too when the SDK
+  stopped while the person had not decided.
 - The card (`number`, `securityValue` for the CVC, `expMonth`, `expYear`, `validUntil`, `last4`,
   `brand`) stays in this process. Printing or serializing the result shows only the last four
   digits. It never appears in an error.

package/dist/chunk-PVMUL3JC.mjs

@@ -0,0 +1,30 @@
+// src/link-approval.ts
+function safeLinkApprovalUrl(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 2048) return void 0;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return void 0;
+  }
+  if (url.protocol !== "https:" || url.username !== "" || url.password !== "" || url.port !== "" || !(url.hostname === "link.com" || url.hostname.endsWith(".link.com"))) {
+    return void 0;
+  }
+  url.hash = "";
+  return url.toString();
+}
+function linkTime(value) {
+  let ms = Number.NaN;
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    ms = value < 1e12 ? value * 1e3 : value;
+  } else if (typeof value === "string" && value.length > 0 && value.length <= 64) {
+    ms = Date.parse(value);
+  }
+  const date = new Date(ms);
+  return Number.isNaN(date.getTime()) ? void 0 : date.toISOString();
+}
+
+export {
+  safeLinkApprovalUrl,
+  linkTime
+};

package/dist/index.d.mts

@@ -2643,6 +2643,33 @@ interface WaitForCheckoutApprovalOptions {
     signal?: AbortSignal;
 }
 
+/**
+ * The Link card request is waiting for the person. Conto has already approved
+ * the purchase, and Link has created the request.
+ */
+interface LinkApprovalEvent {
+    /** The checkpoint Conto approved. */
+    checkpoint: CheckoutCheckpoint;
+    /** The Link spend request id, such as lsrq_... */
+    linkRequestId: string;
+    /**
+     * The Stripe Link page where the person can approve on the web while signed
+     * in to Link, so they do not need the Link app. Only an HTTPS link.com address
+     * is passed. Absent when Link gave none or it did not pass that check. The
+     * person can still approve in the Link app.
+     */
+    approvalUrl?: string;
+    /** When Link stops accepting approval, as an ISO 8601 time, when Link reports it. */
+    approvalExpiresAt?: string;
+}
+/**
+ * Called once when the Link card request is waiting for the person, after
+ * Conto approved the purchase and before the SDK starts waiting. Show
+ * approvalUrl to the person. The SDK does not wait for it to finish, and an
+ * error it throws or rejects with does not affect the purchase. A retry that
+ * resumes a waiting request calls it again with the same URL.
+ */
+type LinkApprovalCallback = (event: LinkApprovalEvent) => void | Promise<void>;
 /**
  * A Link card for one purchase: the checkpoint begin input plus the Link
  * wallet that runs in your environment. The checkout method is always LINK.
@@ -2654,6 +2681,8 @@ interface GetLinkCardInput extends Omit<BeginCheckoutCheckpointInput, 'checkoutM
     ownerApprovalTimeoutMs?: number;
     /** How long to wait for the person to approve in Link. Defaults to 10 minutes. */
     linkApprovalTimeoutMs?: number;
+    /** Called once with the Link approval page when the person needs to approve in Link. */
+    onLinkApproval?: LinkApprovalCallback;
     signal?: AbortSignal;
 }
 /** A new Link card for a changed final total. */
@@ -2667,6 +2696,8 @@ interface ReplaceLinkCardInput {
     totals?: CommerceTotalInput[];
     ownerApprovalTimeoutMs?: number;
     linkApprovalTimeoutMs?: number;
+    /** Called once with the Link approval page when the person needs to approve in Link. */
+    onLinkApproval?: LinkApprovalCallback;
     signal?: AbortSignal;
 }
 interface LinkCardResult {
@@ -3380,6 +3411,13 @@ declare class CheckoutApprovalTimeoutError extends ContoError {
 declare class LinkCardError extends ContoError {
     readonly checkpoint: CheckoutCheckpoint;
     readonly linkRequestId?: string;
+    /**
+     * The Stripe Link page where the person could approve the request, set when
+     * the SDK stopped while the request was waiting for them. It works only while
+     * the request is still open in Link. When holdReleased is true, Conto has
+     * already cancelled the request.
+     */
+    readonly approvalUrl?: string;
     /** True when Conto cancelled the checkpoint and released the held spend. */
     readonly holdReleased: boolean;
     constructor(input: {
@@ -3387,6 +3425,7 @@ declare class LinkCardError extends ContoError {
         code: string;
         checkpoint: CheckoutCheckpoint;
         linkRequestId?: string;
+        approvalUrl?: string;
         holdReleased: boolean;
         retryGuidance?: string;
     });
@@ -3854,7 +3893,9 @@ declare class CheckoutClient {
      * 1. Conto runs checkpoint 1 and holds the spend. When a rule requires the
      *    owner's approval, this waits for it.
      * 2. Only then does the wallet ask Link for a card for exactly the approved
-     *    amount at this merchant. The person approves it in Link.
+     *    amount at this merchant. The person approves it in Link. Pass
+     *    onLinkApproval to get Link's approval page, so they can approve on the
+     *    web without the Link app.
      * 3. The card is returned. It never reaches Conto.
      *
      * Then fill in the card, call confirm(result.checkpoint, { amountMinor,
@@ -3880,4 +3921,4 @@ declare class CheckoutClient {
 }
 
 export { AdminPurchasingClient, BrowserActionFinalizationPendingError, BrowserCheckoutTargetVerificationError, CardsClient, CheckoutApprovalDeniedError, CheckoutApprovalExpiredError, CheckoutApprovalPendingError, CheckoutApprovalTimeoutError, CheckoutCheckpointClosedError, CheckoutClient, ConnectedCardsClient, Conto, ContoAdmin, ContoAdminError, ContoError, ControlledExternalCardPaymentTool, ExternalCardConfirmationPendingError, Conto as Giro, ContoError as GiroError, LinkCardCredential, LinkCardDeniedError, LinkCardError, LinkCardExpiredError, LinkCardTimeoutError, LinkWallet, LinkWalletUnavailableError, OrganizationPurchasesClient, OrganizationRecurringPurchasesClient, PurchasesClient, RecurringPurchasesClient, TestCardsClient, canonicalizeBrowserCheckoutTarget, createVerifiedBrowserCheckoutDriver, Conto as default, fingerprintBrowserCheckoutTarget, isFinalPurchaseStatus, parseServerSentEvents, verifyPurchaseWebhook };
-export type { AdminExternalCardOverlayEnforcement, Agent, AgentCheckoutAction, AgentCheckoutActionKind, AgentExternalCard, AgentSetupResult, AgentStatus, AgentType, AgentWalletLink, ApprovedExternalCardExecution, AssignExternalCardInput, AssignedPolicy, AuthorizeCheckoutActionResult, BeginCheckoutCheckpointInput, BeginCommerceExecutionInput, BrowserActionClaimResult, BrowserActionDispatchObservationInput, BrowserActionFinalizeResult, BrowserCheckoutAction, BrowserCheckoutTargetResolver, BrowserCheckoutTargetSnapshot, BrowserCheckoutTargetVerificationCode, CancellationOutcome, CanonicalBrowserCheckoutTargetSnapshot, ChainType, CheckoutActionAuthorization, CheckoutCheckpoint, CheckoutCheckpointApproval, CheckoutCheckpointMethod, CheckoutCheckpointNextAction, CheckoutCheckpointStage, CheckoutOutcome, CheckoutPaymentReference, CommerceCheckoutMethod, CommerceContextRequirement, CommerceExecution, CommerceExecutionAdapterKind, CommerceExecutionArtifactKind, CommerceExecutionChannel, CommerceExecutionConstraint, CommerceExecutionConstraintCoverage, CommerceExecutionConstraintCoverageLevel, CommerceExecutionDeliveryMode, CommerceExecutionEvidence, CommerceExecutionProvider, CommerceExecutionResult, CommerceExecutionSourceKind, CommerceExecutionStatus, CommerceFactConfidence, CommerceFactProvenanceInput, CommerceFactSource, CommerceFulfillmentInput, CommerceLineItemInput, CommerceProposalFactKey, CommerceProposalMissingFact, CommerceProposalResolution, CommerceProposalState, CommerceSettlementRail, CommerceTotalInput, CommerceTotalType, ComparePolicyVersionsResponse, ConfirmCheckoutCheckpointInput, ConnectedCardBrief, ConnectedCardCredential, ConnectedCardDrawInput, ConnectedCardDrawMerchant, ConnectedCardDrawResult, ConnectedCardDrawable, ConnectedCardListResult, ConnectedCardMandate, ConnectedCardMandateMerchant, ConnectedCardOutcomeReport, ConnectedCardOutcomeReportResult, ConnectedCardReference, ContoAdminConfig, ContoConfig, ContoRequestOptions, ControlledExternalCardPaymentResult, CreateAgentInput, CreatePolicyInput, CreatePolicyRuleInput, CreatePurchaseInput, CreateSdkKeyInput, CreateSdkKeyResult, CreateWalletInput, CustodyType, CustomerCustodyMode, CustomerWalletControlModel, CustomerWalletKeyAccess, DelegationType, ExecuteCommerceExecutionResult, ExternalCard, ExternalCardApprovalInput, ExternalCardApprovalResult, ExternalCardConfirmationInput, ExternalCardConfirmationResult, ExternalCardExecutionClaimResult, ExternalCardExecutionResult, ExternalCardExecutor, ExternalCardOverlayEnforcement, ExternalCardRequestStatusResult, ExternalWalletApprovalInput, ExternalWalletApprovalResult, ExternalWalletConfirmationInput, ExternalWalletConfirmationResult, FreezeAgentInput, GetLinkCardInput, ContoConfig as GiroConfig, GuardCheckoutResult, GuardedBrowserDispatchResult, GuardedCheckoutInput, LinkCardResult, LinkWalletInput, ListAgentsParams, ListAgentsResponse, ListPoliciesParams, ListPoliciesResponse, ListPolicyVersionsResponse, ListWalletsParams, ListWalletsResponse, MppBudgetResult, MppPreAuthorizeInput, MppPreAuthorizeResult, MppRecordInput, MppRecordResult, NormalizeCommerceProposalInput, OrganizationMember, PaginatedResponse, PaginationParams, PauseExternalCardAssignmentResult, PaymentExecuteResult, PaymentRequestInput, PaymentRequestResult, PaymentStatusResult, Policy, PolicyRule, PolicyType, PolicyVersionChangeType, PolicyVersionDetail, PolicyVersionDiff, PolicyVersionFieldChange, PolicyVersionSnapshot, PolicyVersionSnapshotRule, PolicyVersionSummary, PrivilegedBrowserCheckoutDriver, ProtocolBudgetResult, ProtocolPreAuthorizeResult, ProtocolRecordGrant, ProtocolRecordGrantResult, ProtocolServiceSummary, ProtocolServicesResult, ProveWalletOwnershipInput, ProvisionWalletResult, Purchase, PurchaseAction, PurchaseActionAuthority, PurchaseActionKind, PurchaseAllowance, PurchaseBuyer, PurchaseBuyerCompanyCard, PurchaseBuyerCompanyCardLimits, PurchaseBuyerKitchenContext, PurchaseCompanyCard, PurchaseDelegation, PurchaseEvent, PurchaseEventPage, PurchaseEvidence, PurchaseGrocery, PurchaseGroceryItem, PurchaseGroceryList, PurchaseHostedLink, PurchaseItem, PurchaseKitchenContext, PurchaseKitchenInventoryItem, PurchaseKitchenListItem, PurchaseKitchenPreferences, PurchaseKitchenRecipe, PurchaseKitchenUsual, PurchaseList, PurchaseMoney, PurchasePaymentMethod, PurchasePhase, PurchaseRequest, PurchaseResponseAck, PurchaseStatus, PurchasingCapabilities, PurchasingSettings, RecurringPurchase, RecurringPurchaseCycleResult, RecurringPurchaseCycleStatus, RefreshBalanceResult, RegisterExternalCardInput, ReplaceLinkCardInput, ReportCheckoutOutcomeInput, RollbackPolicyVersionResponse, RuleAction, RuleOperator, RuleType, RunGuardedCheckoutResult, SdkKey, SdkKeyType, SetupCapabilityState, SetupCardDiagnostics, SetupDiagnosticAction, SetupDiagnosticIssue, SetupDiagnosticIssueCode, SetupDiagnostics, SetupWalletDiagnostics, TestCardCredential, TestCardDrawResult, TestCardDrawable, TestCardListResult, TestCardReceipt, TestCheckoutInput, TestCheckoutResult, TestMerchant, TestMerchantProduct, UnfreezeAgentInput, UpdateAgentInput, UpdateExternalCardAssignmentInput, UpdatePolicyInput, UpdatePolicyRuleInput, UpdateWalletInput, VerifiedBrowserCheckoutTarget, WaitForCheckoutApprovalOptions, Wallet, WalletChainBalanceSnapshot, WalletOwnershipChallenge, WalletOwnershipProof, WalletStatus, WalletType, WatchPurchaseOptions, X402Authorization, X402BudgetResult, X402PayInput, X402PayResult, X402PaymentRequirements, X402PreAuthorizeInput, X402PreAuthorizeResult, X402RecordInput, X402RecordResult };
+export type { AdminExternalCardOverlayEnforcement, Agent, AgentCheckoutAction, AgentCheckoutActionKind, AgentExternalCard, AgentSetupResult, AgentStatus, AgentType, AgentWalletLink, ApprovedExternalCardExecution, AssignExternalCardInput, AssignedPolicy, AuthorizeCheckoutActionResult, BeginCheckoutCheckpointInput, BeginCommerceExecutionInput, BrowserActionClaimResult, BrowserActionDispatchObservationInput, BrowserActionFinalizeResult, BrowserCheckoutAction, BrowserCheckoutTargetResolver, BrowserCheckoutTargetSnapshot, BrowserCheckoutTargetVerificationCode, CancellationOutcome, CanonicalBrowserCheckoutTargetSnapshot, ChainType, CheckoutActionAuthorization, CheckoutCheckpoint, CheckoutCheckpointApproval, CheckoutCheckpointMethod, CheckoutCheckpointNextAction, CheckoutCheckpointStage, CheckoutOutcome, CheckoutPaymentReference, CommerceCheckoutMethod, CommerceContextRequirement, CommerceExecution, CommerceExecutionAdapterKind, CommerceExecutionArtifactKind, CommerceExecutionChannel, CommerceExecutionConstraint, CommerceExecutionConstraintCoverage, CommerceExecutionConstraintCoverageLevel, CommerceExecutionDeliveryMode, CommerceExecutionEvidence, CommerceExecutionProvider, CommerceExecutionResult, CommerceExecutionSourceKind, CommerceExecutionStatus, CommerceFactConfidence, CommerceFactProvenanceInput, CommerceFactSource, CommerceFulfillmentInput, CommerceLineItemInput, CommerceProposalFactKey, CommerceProposalMissingFact, CommerceProposalResolution, CommerceProposalState, CommerceSettlementRail, CommerceTotalInput, CommerceTotalType, ComparePolicyVersionsResponse, ConfirmCheckoutCheckpointInput, ConnectedCardBrief, ConnectedCardCredential, ConnectedCardDrawInput, ConnectedCardDrawMerchant, ConnectedCardDrawResult, ConnectedCardDrawable, ConnectedCardListResult, ConnectedCardMandate, ConnectedCardMandateMerchant, ConnectedCardOutcomeReport, ConnectedCardOutcomeReportResult, ConnectedCardReference, ContoAdminConfig, ContoConfig, ContoRequestOptions, ControlledExternalCardPaymentResult, CreateAgentInput, CreatePolicyInput, CreatePolicyRuleInput, CreatePurchaseInput, CreateSdkKeyInput, CreateSdkKeyResult, CreateWalletInput, CustodyType, CustomerCustodyMode, CustomerWalletControlModel, CustomerWalletKeyAccess, DelegationType, ExecuteCommerceExecutionResult, ExternalCard, ExternalCardApprovalInput, ExternalCardApprovalResult, ExternalCardConfirmationInput, ExternalCardConfirmationResult, ExternalCardExecutionClaimResult, ExternalCardExecutionResult, ExternalCardExecutor, ExternalCardOverlayEnforcement, ExternalCardRequestStatusResult, ExternalWalletApprovalInput, ExternalWalletApprovalResult, ExternalWalletConfirmationInput, ExternalWalletConfirmationResult, FreezeAgentInput, GetLinkCardInput, ContoConfig as GiroConfig, GuardCheckoutResult, GuardedBrowserDispatchResult, GuardedCheckoutInput, LinkApprovalCallback, LinkApprovalEvent, LinkCardResult, LinkWalletInput, ListAgentsParams, ListAgentsResponse, ListPoliciesParams, ListPoliciesResponse, ListPolicyVersionsResponse, ListWalletsParams, ListWalletsResponse, MppBudgetResult, MppPreAuthorizeInput, MppPreAuthorizeResult, MppRecordInput, MppRecordResult, NormalizeCommerceProposalInput, OrganizationMember, PaginatedResponse, PaginationParams, PauseExternalCardAssignmentResult, PaymentExecuteResult, PaymentRequestInput, PaymentRequestResult, PaymentStatusResult, Policy, PolicyRule, PolicyType, PolicyVersionChangeType, PolicyVersionDetail, PolicyVersionDiff, PolicyVersionFieldChange, PolicyVersionSnapshot, PolicyVersionSnapshotRule, PolicyVersionSummary, PrivilegedBrowserCheckoutDriver, ProtocolBudgetResult, ProtocolPreAuthorizeResult, ProtocolRecordGrant, ProtocolRecordGrantResult, ProtocolServiceSummary, ProtocolServicesResult, ProveWalletOwnershipInput, ProvisionWalletResult, Purchase, PurchaseAction, PurchaseActionAuthority, PurchaseActionKind, PurchaseAllowance, PurchaseBuyer, PurchaseBuyerCompanyCard, PurchaseBuyerCompanyCardLimits, PurchaseBuyerKitchenContext, PurchaseCompanyCard, PurchaseDelegation, PurchaseEvent, PurchaseEventPage, PurchaseEvidence, PurchaseGrocery, PurchaseGroceryItem, PurchaseGroceryList, PurchaseHostedLink, PurchaseItem, PurchaseKitchenContext, PurchaseKitchenInventoryItem, PurchaseKitchenListItem, PurchaseKitchenPreferences, PurchaseKitchenRecipe, PurchaseKitchenUsual, PurchaseList, PurchaseMoney, PurchasePaymentMethod, PurchasePhase, PurchaseRequest, PurchaseResponseAck, PurchaseStatus, PurchasingCapabilities, PurchasingSettings, RecurringPurchase, RecurringPurchaseCycleResult, RecurringPurchaseCycleStatus, RefreshBalanceResult, RegisterExternalCardInput, ReplaceLinkCardInput, ReportCheckoutOutcomeInput, RollbackPolicyVersionResponse, RuleAction, RuleOperator, RuleType, RunGuardedCheckoutResult, SdkKey, SdkKeyType, SetupCapabilityState, SetupCardDiagnostics, SetupDiagnosticAction, SetupDiagnosticIssue, SetupDiagnosticIssueCode, SetupDiagnostics, SetupWalletDiagnostics, TestCardCredential, TestCardDrawResult, TestCardDrawable, TestCardListResult, TestCardReceipt, TestCheckoutInput, TestCheckoutResult, TestMerchant, TestMerchantProduct, UnfreezeAgentInput, UpdateAgentInput, UpdateExternalCardAssignmentInput, UpdatePolicyInput, UpdatePolicyRuleInput, UpdateWalletInput, VerifiedBrowserCheckoutTarget, WaitForCheckoutApprovalOptions, Wallet, WalletChainBalanceSnapshot, WalletOwnershipChallenge, WalletOwnershipProof, WalletStatus, WalletType, WatchPurchaseOptions, X402Authorization, X402BudgetResult, X402PayInput, X402PayResult, X402PaymentRequirements, X402PreAuthorizeInput, X402PreAuthorizeResult, X402RecordInput, X402RecordResult };

package/dist/index.d.ts

@@ -2643,6 +2643,33 @@ interface WaitForCheckoutApprovalOptions {
     signal?: AbortSignal;
 }
 
+/**
+ * The Link card request is waiting for the person. Conto has already approved
+ * the purchase, and Link has created the request.
+ */
+interface LinkApprovalEvent {
+    /** The checkpoint Conto approved. */
+    checkpoint: CheckoutCheckpoint;
+    /** The Link spend request id, such as lsrq_... */
+    linkRequestId: string;
+    /**
+     * The Stripe Link page where the person can approve on the web while signed
+     * in to Link, so they do not need the Link app. Only an HTTPS link.com address
+     * is passed. Absent when Link gave none or it did not pass that check. The
+     * person can still approve in the Link app.
+     */
+    approvalUrl?: string;
+    /** When Link stops accepting approval, as an ISO 8601 time, when Link reports it. */
+    approvalExpiresAt?: string;
+}
+/**
+ * Called once when the Link card request is waiting for the person, after
+ * Conto approved the purchase and before the SDK starts waiting. Show
+ * approvalUrl to the person. The SDK does not wait for it to finish, and an
+ * error it throws or rejects with does not affect the purchase. A retry that
+ * resumes a waiting request calls it again with the same URL.
+ */
+type LinkApprovalCallback = (event: LinkApprovalEvent) => void | Promise<void>;
 /**
  * A Link card for one purchase: the checkpoint begin input plus the Link
  * wallet that runs in your environment. The checkout method is always LINK.
@@ -2654,6 +2681,8 @@ interface GetLinkCardInput extends Omit<BeginCheckoutCheckpointInput, 'checkoutM
     ownerApprovalTimeoutMs?: number;
     /** How long to wait for the person to approve in Link. Defaults to 10 minutes. */
     linkApprovalTimeoutMs?: number;
+    /** Called once with the Link approval page when the person needs to approve in Link. */
+    onLinkApproval?: LinkApprovalCallback;
     signal?: AbortSignal;
 }
 /** A new Link card for a changed final total. */
@@ -2667,6 +2696,8 @@ interface ReplaceLinkCardInput {
     totals?: CommerceTotalInput[];
     ownerApprovalTimeoutMs?: number;
     linkApprovalTimeoutMs?: number;
+    /** Called once with the Link approval page when the person needs to approve in Link. */
+    onLinkApproval?: LinkApprovalCallback;
     signal?: AbortSignal;
 }
 interface LinkCardResult {
@@ -3380,6 +3411,13 @@ declare class CheckoutApprovalTimeoutError extends ContoError {
 declare class LinkCardError extends ContoError {
     readonly checkpoint: CheckoutCheckpoint;
     readonly linkRequestId?: string;
+    /**
+     * The Stripe Link page where the person could approve the request, set when
+     * the SDK stopped while the request was waiting for them. It works only while
+     * the request is still open in Link. When holdReleased is true, Conto has
+     * already cancelled the request.
+     */
+    readonly approvalUrl?: string;
     /** True when Conto cancelled the checkpoint and released the held spend. */
     readonly holdReleased: boolean;
     constructor(input: {
@@ -3387,6 +3425,7 @@ declare class LinkCardError extends ContoError {
         code: string;
         checkpoint: CheckoutCheckpoint;
         linkRequestId?: string;
+        approvalUrl?: string;
         holdReleased: boolean;
         retryGuidance?: string;
     });
@@ -3854,7 +3893,9 @@ declare class CheckoutClient {
      * 1. Conto runs checkpoint 1 and holds the spend. When a rule requires the
      *    owner's approval, this waits for it.
      * 2. Only then does the wallet ask Link for a card for exactly the approved
-     *    amount at this merchant. The person approves it in Link.
+     *    amount at this merchant. The person approves it in Link. Pass
+     *    onLinkApproval to get Link's approval page, so they can approve on the
+     *    web without the Link app.
      * 3. The card is returned. It never reaches Conto.
      *
      * Then fill in the card, call confirm(result.checkpoint, { amountMinor,
@@ -3880,4 +3921,4 @@ declare class CheckoutClient {
 }
 
 export { AdminPurchasingClient, BrowserActionFinalizationPendingError, BrowserCheckoutTargetVerificationError, CardsClient, CheckoutApprovalDeniedError, CheckoutApprovalExpiredError, CheckoutApprovalPendingError, CheckoutApprovalTimeoutError, CheckoutCheckpointClosedError, CheckoutClient, ConnectedCardsClient, Conto, ContoAdmin, ContoAdminError, ContoError, ControlledExternalCardPaymentTool, ExternalCardConfirmationPendingError, Conto as Giro, ContoError as GiroError, LinkCardCredential, LinkCardDeniedError, LinkCardError, LinkCardExpiredError, LinkCardTimeoutError, LinkWallet, LinkWalletUnavailableError, OrganizationPurchasesClient, OrganizationRecurringPurchasesClient, PurchasesClient, RecurringPurchasesClient, TestCardsClient, canonicalizeBrowserCheckoutTarget, createVerifiedBrowserCheckoutDriver, Conto as default, fingerprintBrowserCheckoutTarget, isFinalPurchaseStatus, parseServerSentEvents, verifyPurchaseWebhook };
-export type { AdminExternalCardOverlayEnforcement, Agent, AgentCheckoutAction, AgentCheckoutActionKind, AgentExternalCard, AgentSetupResult, AgentStatus, AgentType, AgentWalletLink, ApprovedExternalCardExecution, AssignExternalCardInput, AssignedPolicy, AuthorizeCheckoutActionResult, BeginCheckoutCheckpointInput, BeginCommerceExecutionInput, BrowserActionClaimResult, BrowserActionDispatchObservationInput, BrowserActionFinalizeResult, BrowserCheckoutAction, BrowserCheckoutTargetResolver, BrowserCheckoutTargetSnapshot, BrowserCheckoutTargetVerificationCode, CancellationOutcome, CanonicalBrowserCheckoutTargetSnapshot, ChainType, CheckoutActionAuthorization, CheckoutCheckpoint, CheckoutCheckpointApproval, CheckoutCheckpointMethod, CheckoutCheckpointNextAction, CheckoutCheckpointStage, CheckoutOutcome, CheckoutPaymentReference, CommerceCheckoutMethod, CommerceContextRequirement, CommerceExecution, CommerceExecutionAdapterKind, CommerceExecutionArtifactKind, CommerceExecutionChannel, CommerceExecutionConstraint, CommerceExecutionConstraintCoverage, CommerceExecutionConstraintCoverageLevel, CommerceExecutionDeliveryMode, CommerceExecutionEvidence, CommerceExecutionProvider, CommerceExecutionResult, CommerceExecutionSourceKind, CommerceExecutionStatus, CommerceFactConfidence, CommerceFactProvenanceInput, CommerceFactSource, CommerceFulfillmentInput, CommerceLineItemInput, CommerceProposalFactKey, CommerceProposalMissingFact, CommerceProposalResolution, CommerceProposalState, CommerceSettlementRail, CommerceTotalInput, CommerceTotalType, ComparePolicyVersionsResponse, ConfirmCheckoutCheckpointInput, ConnectedCardBrief, ConnectedCardCredential, ConnectedCardDrawInput, ConnectedCardDrawMerchant, ConnectedCardDrawResult, ConnectedCardDrawable, ConnectedCardListResult, ConnectedCardMandate, ConnectedCardMandateMerchant, ConnectedCardOutcomeReport, ConnectedCardOutcomeReportResult, ConnectedCardReference, ContoAdminConfig, ContoConfig, ContoRequestOptions, ControlledExternalCardPaymentResult, CreateAgentInput, CreatePolicyInput, CreatePolicyRuleInput, CreatePurchaseInput, CreateSdkKeyInput, CreateSdkKeyResult, CreateWalletInput, CustodyType, CustomerCustodyMode, CustomerWalletControlModel, CustomerWalletKeyAccess, DelegationType, ExecuteCommerceExecutionResult, ExternalCard, ExternalCardApprovalInput, ExternalCardApprovalResult, ExternalCardConfirmationInput, ExternalCardConfirmationResult, ExternalCardExecutionClaimResult, ExternalCardExecutionResult, ExternalCardExecutor, ExternalCardOverlayEnforcement, ExternalCardRequestStatusResult, ExternalWalletApprovalInput, ExternalWalletApprovalResult, ExternalWalletConfirmationInput, ExternalWalletConfirmationResult, FreezeAgentInput, GetLinkCardInput, ContoConfig as GiroConfig, GuardCheckoutResult, GuardedBrowserDispatchResult, GuardedCheckoutInput, LinkCardResult, LinkWalletInput, ListAgentsParams, ListAgentsResponse, ListPoliciesParams, ListPoliciesResponse, ListPolicyVersionsResponse, ListWalletsParams, ListWalletsResponse, MppBudgetResult, MppPreAuthorizeInput, MppPreAuthorizeResult, MppRecordInput, MppRecordResult, NormalizeCommerceProposalInput, OrganizationMember, PaginatedResponse, PaginationParams, PauseExternalCardAssignmentResult, PaymentExecuteResult, PaymentRequestInput, PaymentRequestResult, PaymentStatusResult, Policy, PolicyRule, PolicyType, PolicyVersionChangeType, PolicyVersionDetail, PolicyVersionDiff, PolicyVersionFieldChange, PolicyVersionSnapshot, PolicyVersionSnapshotRule, PolicyVersionSummary, PrivilegedBrowserCheckoutDriver, ProtocolBudgetResult, ProtocolPreAuthorizeResult, ProtocolRecordGrant, ProtocolRecordGrantResult, ProtocolServiceSummary, ProtocolServicesResult, ProveWalletOwnershipInput, ProvisionWalletResult, Purchase, PurchaseAction, PurchaseActionAuthority, PurchaseActionKind, PurchaseAllowance, PurchaseBuyer, PurchaseBuyerCompanyCard, PurchaseBuyerCompanyCardLimits, PurchaseBuyerKitchenContext, PurchaseCompanyCard, PurchaseDelegation, PurchaseEvent, PurchaseEventPage, PurchaseEvidence, PurchaseGrocery, PurchaseGroceryItem, PurchaseGroceryList, PurchaseHostedLink, PurchaseItem, PurchaseKitchenContext, PurchaseKitchenInventoryItem, PurchaseKitchenListItem, PurchaseKitchenPreferences, PurchaseKitchenRecipe, PurchaseKitchenUsual, PurchaseList, PurchaseMoney, PurchasePaymentMethod, PurchasePhase, PurchaseRequest, PurchaseResponseAck, PurchaseStatus, PurchasingCapabilities, PurchasingSettings, RecurringPurchase, RecurringPurchaseCycleResult, RecurringPurchaseCycleStatus, RefreshBalanceResult, RegisterExternalCardInput, ReplaceLinkCardInput, ReportCheckoutOutcomeInput, RollbackPolicyVersionResponse, RuleAction, RuleOperator, RuleType, RunGuardedCheckoutResult, SdkKey, SdkKeyType, SetupCapabilityState, SetupCardDiagnostics, SetupDiagnosticAction, SetupDiagnosticIssue, SetupDiagnosticIssueCode, SetupDiagnostics, SetupWalletDiagnostics, TestCardCredential, TestCardDrawResult, TestCardDrawable, TestCardListResult, TestCardReceipt, TestCheckoutInput, TestCheckoutResult, TestMerchant, TestMerchantProduct, UnfreezeAgentInput, UpdateAgentInput, UpdateExternalCardAssignmentInput, UpdatePolicyInput, UpdatePolicyRuleInput, UpdateWalletInput, VerifiedBrowserCheckoutTarget, WaitForCheckoutApprovalOptions, Wallet, WalletChainBalanceSnapshot, WalletOwnershipChallenge, WalletOwnershipProof, WalletStatus, WalletType, WatchPurchaseOptions, X402Authorization, X402BudgetResult, X402PayInput, X402PayResult, X402PaymentRequirements, X402PreAuthorizeInput, X402PreAuthorizeResult, X402RecordInput, X402RecordResult };
+export type { AdminExternalCardOverlayEnforcement, Agent, AgentCheckoutAction, AgentCheckoutActionKind, AgentExternalCard, AgentSetupResult, AgentStatus, AgentType, AgentWalletLink, ApprovedExternalCardExecution, AssignExternalCardInput, AssignedPolicy, AuthorizeCheckoutActionResult, BeginCheckoutCheckpointInput, BeginCommerceExecutionInput, BrowserActionClaimResult, BrowserActionDispatchObservationInput, BrowserActionFinalizeResult, BrowserCheckoutAction, BrowserCheckoutTargetResolver, BrowserCheckoutTargetSnapshot, BrowserCheckoutTargetVerificationCode, CancellationOutcome, CanonicalBrowserCheckoutTargetSnapshot, ChainType, CheckoutActionAuthorization, CheckoutCheckpoint, CheckoutCheckpointApproval, CheckoutCheckpointMethod, CheckoutCheckpointNextAction, CheckoutCheckpointStage, CheckoutOutcome, CheckoutPaymentReference, CommerceCheckoutMethod, CommerceContextRequirement, CommerceExecution, CommerceExecutionAdapterKind, CommerceExecutionArtifactKind, CommerceExecutionChannel, CommerceExecutionConstraint, CommerceExecutionConstraintCoverage, CommerceExecutionConstraintCoverageLevel, CommerceExecutionDeliveryMode, CommerceExecutionEvidence, CommerceExecutionProvider, CommerceExecutionResult, CommerceExecutionSourceKind, CommerceExecutionStatus, CommerceFactConfidence, CommerceFactProvenanceInput, CommerceFactSource, CommerceFulfillmentInput, CommerceLineItemInput, CommerceProposalFactKey, CommerceProposalMissingFact, CommerceProposalResolution, CommerceProposalState, CommerceSettlementRail, CommerceTotalInput, CommerceTotalType, ComparePolicyVersionsResponse, ConfirmCheckoutCheckpointInput, ConnectedCardBrief, ConnectedCardCredential, ConnectedCardDrawInput, ConnectedCardDrawMerchant, ConnectedCardDrawResult, ConnectedCardDrawable, ConnectedCardListResult, ConnectedCardMandate, ConnectedCardMandateMerchant, ConnectedCardOutcomeReport, ConnectedCardOutcomeReportResult, ConnectedCardReference, ContoAdminConfig, ContoConfig, ContoRequestOptions, ControlledExternalCardPaymentResult, CreateAgentInput, CreatePolicyInput, CreatePolicyRuleInput, CreatePurchaseInput, CreateSdkKeyInput, CreateSdkKeyResult, CreateWalletInput, CustodyType, CustomerCustodyMode, CustomerWalletControlModel, CustomerWalletKeyAccess, DelegationType, ExecuteCommerceExecutionResult, ExternalCard, ExternalCardApprovalInput, ExternalCardApprovalResult, ExternalCardConfirmationInput, ExternalCardConfirmationResult, ExternalCardExecutionClaimResult, ExternalCardExecutionResult, ExternalCardExecutor, ExternalCardOverlayEnforcement, ExternalCardRequestStatusResult, ExternalWalletApprovalInput, ExternalWalletApprovalResult, ExternalWalletConfirmationInput, ExternalWalletConfirmationResult, FreezeAgentInput, GetLinkCardInput, ContoConfig as GiroConfig, GuardCheckoutResult, GuardedBrowserDispatchResult, GuardedCheckoutInput, LinkApprovalCallback, LinkApprovalEvent, LinkCardResult, LinkWalletInput, ListAgentsParams, ListAgentsResponse, ListPoliciesParams, ListPoliciesResponse, ListPolicyVersionsResponse, ListWalletsParams, ListWalletsResponse, MppBudgetResult, MppPreAuthorizeInput, MppPreAuthorizeResult, MppRecordInput, MppRecordResult, NormalizeCommerceProposalInput, OrganizationMember, PaginatedResponse, PaginationParams, PauseExternalCardAssignmentResult, PaymentExecuteResult, PaymentRequestInput, PaymentRequestResult, PaymentStatusResult, Policy, PolicyRule, PolicyType, PolicyVersionChangeType, PolicyVersionDetail, PolicyVersionDiff, PolicyVersionFieldChange, PolicyVersionSnapshot, PolicyVersionSnapshotRule, PolicyVersionSummary, PrivilegedBrowserCheckoutDriver, ProtocolBudgetResult, ProtocolPreAuthorizeResult, ProtocolRecordGrant, ProtocolRecordGrantResult, ProtocolServiceSummary, ProtocolServicesResult, ProveWalletOwnershipInput, ProvisionWalletResult, Purchase, PurchaseAction, PurchaseActionAuthority, PurchaseActionKind, PurchaseAllowance, PurchaseBuyer, PurchaseBuyerCompanyCard, PurchaseBuyerCompanyCardLimits, PurchaseBuyerKitchenContext, PurchaseCompanyCard, PurchaseDelegation, PurchaseEvent, PurchaseEventPage, PurchaseEvidence, PurchaseGrocery, PurchaseGroceryItem, PurchaseGroceryList, PurchaseHostedLink, PurchaseItem, PurchaseKitchenContext, PurchaseKitchenInventoryItem, PurchaseKitchenListItem, PurchaseKitchenPreferences, PurchaseKitchenRecipe, PurchaseKitchenUsual, PurchaseList, PurchaseMoney, PurchasePaymentMethod, PurchasePhase, PurchaseRequest, PurchaseResponseAck, PurchaseStatus, PurchasingCapabilities, PurchasingSettings, RecurringPurchase, RecurringPurchaseCycleResult, RecurringPurchaseCycleStatus, RefreshBalanceResult, RegisterExternalCardInput, ReplaceLinkCardInput, ReportCheckoutOutcomeInput, RollbackPolicyVersionResponse, RuleAction, RuleOperator, RuleType, RunGuardedCheckoutResult, SdkKey, SdkKeyType, SetupCapabilityState, SetupCardDiagnostics, SetupDiagnosticAction, SetupDiagnosticIssue, SetupDiagnosticIssueCode, SetupDiagnostics, SetupWalletDiagnostics, TestCardCredential, TestCardDrawResult, TestCardDrawable, TestCardListResult, TestCardReceipt, TestCheckoutInput, TestCheckoutResult, TestMerchant, TestMerchantProduct, UnfreezeAgentInput, UpdateAgentInput, UpdateExternalCardAssignmentInput, UpdatePolicyInput, UpdatePolicyRuleInput, UpdateWalletInput, VerifiedBrowserCheckoutTarget, WaitForCheckoutApprovalOptions, Wallet, WalletChainBalanceSnapshot, WalletOwnershipChallenge, WalletOwnershipProof, WalletStatus, WalletType, WatchPurchaseOptions, X402Authorization, X402BudgetResult, X402PayInput, X402PayResult, X402PaymentRequirements, X402PreAuthorizeInput, X402PreAuthorizeResult, X402RecordInput, X402RecordResult };

package/dist/index.js

@@ -47,7 +47,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "@conto_finance/sdk",
-      version: "0.7.0",
+      version: "0.7.1",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -197,6 +197,32 @@ var Sentry2 = __toESM(require("@sentry/node"));
 var import_node_crypto3 = require("crypto");
 var import_package_version2 = __toESM(require_package_version());
 
+// src/link-approval.ts
+function safeLinkApprovalUrl(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 2048) return void 0;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return void 0;
+  }
+  if (url.protocol !== "https:" || url.username !== "" || url.password !== "" || url.port !== "" || !(url.hostname === "link.com" || url.hostname.endsWith(".link.com"))) {
+    return void 0;
+  }
+  url.hash = "";
+  return url.toString();
+}
+function linkTime(value) {
+  let ms = Number.NaN;
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    ms = value < 1e12 ? value * 1e3 : value;
+  } else if (typeof value === "string" && value.length > 0 && value.length <= 64) {
+    ms = Date.parse(value);
+  }
+  const date = new Date(ms);
+  return Number.isNaN(date.getTime()) ? void 0 : date.toISOString();
+}
+
 // src/purchases.ts
 var import_node_crypto = require("crypto");
 var TERMINAL = /* @__PURE__ */ new Set(["succeeded", "blocked", "failed", "cancelled"]);
@@ -1684,6 +1710,8 @@ var LinkCardError = class extends ContoError {
     this.name = "LinkCardError";
     this.checkpoint = input.checkpoint;
     if (input.linkRequestId) this.linkRequestId = input.linkRequestId;
+    const approvalUrl = safeLinkApprovalUrl(input.approvalUrl);
+    if (approvalUrl) this.approvalUrl = approvalUrl;
     this.holdReleased = input.holdReleased;
   }
 };
@@ -2991,6 +3019,11 @@ async function closeLinkRequest(wallet, id) {
     return status !== void 0 && LINK_CLOSED_STATUSES.has(status);
   }
 }
+function assertLinkApprovalCallback(callback) {
+  if (callback !== void 0 && typeof callback !== "function") {
+    throw checkoutError("onLinkApproval must be a function");
+  }
+}
 function linkCreatedNothing(error) {
   return errorCode(error) === "LINK_WALLET_UNAVAILABLE" || errorReason(error) === "invalid_input";
 }
@@ -3000,6 +3033,23 @@ var LinkFailureSignal = class extends Error {
     this.failure = failure;
   }
 };
+function linkApprovalDetails(request) {
+  const approvalUrl = safeLinkApprovalUrl(request.approvalUrl);
+  const approvalExpiresAt = linkTime(request.approvalExpiresAt);
+  return {
+    ...approvalUrl ? { approvalUrl } : {},
+    ...approvalExpiresAt ? { approvalExpiresAt } : {}
+  };
+}
+function notifyLinkApproval(callback, event) {
+  try {
+    const result = callback(Object.freeze(event));
+    if (result !== null && typeof result === "object" && "then" in result) {
+      Promise.resolve(result).catch(() => void 0);
+    }
+  } catch {
+  }
+}
 var _client4, _CheckoutClient_instances, linkCardFor_fn;
 var CheckoutClient = class {
   constructor(client) {
@@ -3185,7 +3235,9 @@ var CheckoutClient = class {
    * 1. Conto runs checkpoint 1 and holds the spend. When a rule requires the
    *    owner's approval, this waits for it.
    * 2. Only then does the wallet ask Link for a card for exactly the approved
-   *    amount at this merchant. The person approves it in Link.
+   *    amount at this merchant. The person approves it in Link. Pass
+   *    onLinkApproval to get Link's approval page, so they can approve on the
+   *    web without the Link app.
    * 3. The card is returned. It never reaches Conto.
    *
    * Then fill in the card, call confirm(result.checkpoint, { amountMinor,
@@ -3201,10 +3253,18 @@ var CheckoutClient = class {
    * Link request.
    */
   async getLinkCard(input) {
-    const { wallet, ownerApprovalTimeoutMs, linkApprovalTimeoutMs, signal, ...beginInput } = input;
+    const {
+      wallet,
+      ownerApprovalTimeoutMs,
+      linkApprovalTimeoutMs,
+      onLinkApproval,
+      signal,
+      ...beginInput
+    } = input;
     if (!wallet || typeof wallet.createCardRequest !== "function") {
       throw checkoutError("wallet must be a LinkWallet, such as linkCliWallet()");
     }
+    assertLinkApprovalCallback(onLinkApproval);
     let checkpoint = await this.begin({ ...beginInput, checkoutMethod: "LINK" });
     if (checkpoint.stage === "AWAITING_APPROVAL") {
       checkpoint = await this.waitForApproval(checkpoint, {
@@ -3212,7 +3272,11 @@ var CheckoutClient = class {
         ...signal ? { signal } : {}
       });
     }
-    return __privateMethod(this, _CheckoutClient_instances, linkCardFor_fn).call(this, checkpoint, wallet, linkApprovalTimeoutMs, signal);
+    return __privateMethod(this, _CheckoutClient_instances, linkCardFor_fn).call(this, checkpoint, wallet, {
+      linkApprovalTimeoutMs,
+      signal,
+      onLinkApproval
+    });
   }
   /**
    * The final total differs from the one the Link card covers. This cancels
@@ -3221,10 +3285,18 @@ var CheckoutClient = class {
    * for it. Confirm the returned checkpoint with the same total.
    */
   async replaceLinkCard(previous, input) {
-    const { wallet, amountMinor, ownerApprovalTimeoutMs, linkApprovalTimeoutMs, signal } = input;
+    const {
+      wallet,
+      amountMinor,
+      ownerApprovalTimeoutMs,
+      linkApprovalTimeoutMs,
+      onLinkApproval,
+      signal
+    } = input;
     if (!Number.isSafeInteger(amountMinor) || amountMinor <= 0) {
       throw checkoutError("amountMinor must be a positive integer number of cents");
     }
+    assertLinkApprovalCallback(onLinkApproval);
     if (amountMinor === previous.checkpoint.amountMinor) return previous;
     const old = previous.checkpoint;
     if (!await closeLinkRequest(wallet, previous.linkRequestId)) {
@@ -3263,12 +3335,17 @@ var CheckoutClient = class {
         ...signal ? { signal } : {}
       });
     }
-    return __privateMethod(this, _CheckoutClient_instances, linkCardFor_fn).call(this, checkpoint, wallet, linkApprovalTimeoutMs, signal);
+    return __privateMethod(this, _CheckoutClient_instances, linkCardFor_fn).call(this, checkpoint, wallet, {
+      linkApprovalTimeoutMs,
+      signal,
+      onLinkApproval
+    });
   }
 };
 _client4 = new WeakMap();
 _CheckoutClient_instances = new WeakSet();
-linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 * 6e4, signal) {
+linkCardFor_fn = async function(checkpoint, wallet, options) {
+  const { linkApprovalTimeoutMs = 10 * 6e4, signal, onLinkApproval } = options;
   if (checkpoint.stage !== "APPROVED") {
     throw checkoutError(
       `Conto has not approved a card for this checkpoint (stage ${checkpoint.stage}). Do not pay.`,
@@ -3278,6 +3355,7 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
   const deadline = Date.now() + linkApprovalTimeoutMs;
   const call = signal ? { signal } : {};
   let linkRequestId;
+  let approvalUrl;
   let createStarted = false;
   try {
     const cardRequest = linkCardRequest(checkpoint);
@@ -3298,6 +3376,13 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
         message: "Link returned a request for a different amount."
       });
     }
+    if (LINK_WAITING_STATUSES.has(request.status)) {
+      const details = linkApprovalDetails(request);
+      approvalUrl = details.approvalUrl;
+      if (onLinkApproval) {
+        notifyLinkApproval(onLinkApproval, { checkpoint, linkRequestId: request.id, ...details });
+      }
+    }
     while (linkRequestWaiting(request)) {
       const remainingSeconds = Math.floor((deadline - Date.now()) / 1e3);
       if (remainingSeconds <= 0) {
@@ -3312,6 +3397,7 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
         ...call,
         timeoutSeconds: remainingSeconds
       });
+      approvalUrl = LINK_WAITING_STATUSES.has(request.status) ? linkApprovalDetails(request).approvalUrl ?? approvalUrl : void 0;
       if (linkRequestWaiting(request) && Date.now() - started < 1e3) {
         await sleep2(1e3, signal);
       }
@@ -3343,6 +3429,7 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
         code: "LINK_CARD_NOT_CANCELLED",
         checkpoint,
         linkRequestId,
+        ...approvalUrl ? { approvalUrl } : {},
         holdReleased: false,
         retryGuidance: "Retry with the same input to resume this Link request, or cancel it with wallet.cancel(error.linkRequestId) and then call checkout.cancel(error.checkpoint.id)."
       });
@@ -3356,6 +3443,7 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
       code: failure.code,
       checkpoint,
       ...linkRequestId ? { linkRequestId } : {},
+      ...linkRequestId && approvalUrl ? { approvalUrl } : {},
       holdReleased
     });
   }

package/dist/index.mjs

@@ -1,3 +1,7 @@
+import {
+  linkTime,
+  safeLinkApprovalUrl
+} from "./chunk-PVMUL3JC.mjs";
 import {
   BrowserCheckoutTargetVerificationError,
   canonicalizeBrowserCheckoutTarget,
@@ -18,7 +22,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "@conto_finance/sdk",
-      version: "0.7.0",
+      version: "0.7.1",
       description: "Conto SDK for AI agent payment authorization",
       main: "./dist/index.js",
       module: "./dist/index.mjs",
@@ -1499,6 +1503,8 @@ var LinkCardError = class extends ContoError {
     this.name = "LinkCardError";
     this.checkpoint = input.checkpoint;
     if (input.linkRequestId) this.linkRequestId = input.linkRequestId;
+    const approvalUrl = safeLinkApprovalUrl(input.approvalUrl);
+    if (approvalUrl) this.approvalUrl = approvalUrl;
     this.holdReleased = input.holdReleased;
   }
 };
@@ -2806,6 +2812,11 @@ async function closeLinkRequest(wallet, id) {
     return status !== void 0 && LINK_CLOSED_STATUSES.has(status);
   }
 }
+function assertLinkApprovalCallback(callback) {
+  if (callback !== void 0 && typeof callback !== "function") {
+    throw checkoutError("onLinkApproval must be a function");
+  }
+}
 function linkCreatedNothing(error) {
   return errorCode(error) === "LINK_WALLET_UNAVAILABLE" || errorReason(error) === "invalid_input";
 }
@@ -2815,6 +2826,23 @@ var LinkFailureSignal = class extends Error {
     this.failure = failure;
   }
 };
+function linkApprovalDetails(request) {
+  const approvalUrl = safeLinkApprovalUrl(request.approvalUrl);
+  const approvalExpiresAt = linkTime(request.approvalExpiresAt);
+  return {
+    ...approvalUrl ? { approvalUrl } : {},
+    ...approvalExpiresAt ? { approvalExpiresAt } : {}
+  };
+}
+function notifyLinkApproval(callback, event) {
+  try {
+    const result = callback(Object.freeze(event));
+    if (result !== null && typeof result === "object" && "then" in result) {
+      Promise.resolve(result).catch(() => void 0);
+    }
+  } catch {
+  }
+}
 var _client4, _CheckoutClient_instances, linkCardFor_fn;
 var CheckoutClient = class {
   constructor(client) {
@@ -3000,7 +3028,9 @@ var CheckoutClient = class {
    * 1. Conto runs checkpoint 1 and holds the spend. When a rule requires the
    *    owner's approval, this waits for it.
    * 2. Only then does the wallet ask Link for a card for exactly the approved
-   *    amount at this merchant. The person approves it in Link.
+   *    amount at this merchant. The person approves it in Link. Pass
+   *    onLinkApproval to get Link's approval page, so they can approve on the
+   *    web without the Link app.
    * 3. The card is returned. It never reaches Conto.
    *
    * Then fill in the card, call confirm(result.checkpoint, { amountMinor,
@@ -3016,10 +3046,18 @@ var CheckoutClient = class {
    * Link request.
    */
   async getLinkCard(input) {
-    const { wallet, ownerApprovalTimeoutMs, linkApprovalTimeoutMs, signal, ...beginInput } = input;
+    const {
+      wallet,
+      ownerApprovalTimeoutMs,
+      linkApprovalTimeoutMs,
+      onLinkApproval,
+      signal,
+      ...beginInput
+    } = input;
     if (!wallet || typeof wallet.createCardRequest !== "function") {
       throw checkoutError("wallet must be a LinkWallet, such as linkCliWallet()");
     }
+    assertLinkApprovalCallback(onLinkApproval);
     let checkpoint = await this.begin({ ...beginInput, checkoutMethod: "LINK" });
     if (checkpoint.stage === "AWAITING_APPROVAL") {
       checkpoint = await this.waitForApproval(checkpoint, {
@@ -3027,7 +3065,11 @@ var CheckoutClient = class {
         ...signal ? { signal } : {}
       });
     }
-    return __privateMethod(this, _CheckoutClient_instances, linkCardFor_fn).call(this, checkpoint, wallet, linkApprovalTimeoutMs, signal);
+    return __privateMethod(this, _CheckoutClient_instances, linkCardFor_fn).call(this, checkpoint, wallet, {
+      linkApprovalTimeoutMs,
+      signal,
+      onLinkApproval
+    });
   }
   /**
    * The final total differs from the one the Link card covers. This cancels
@@ -3036,10 +3078,18 @@ var CheckoutClient = class {
    * for it. Confirm the returned checkpoint with the same total.
    */
   async replaceLinkCard(previous, input) {
-    const { wallet, amountMinor, ownerApprovalTimeoutMs, linkApprovalTimeoutMs, signal } = input;
+    const {
+      wallet,
+      amountMinor,
+      ownerApprovalTimeoutMs,
+      linkApprovalTimeoutMs,
+      onLinkApproval,
+      signal
+    } = input;
     if (!Number.isSafeInteger(amountMinor) || amountMinor <= 0) {
       throw checkoutError("amountMinor must be a positive integer number of cents");
     }
+    assertLinkApprovalCallback(onLinkApproval);
     if (amountMinor === previous.checkpoint.amountMinor) return previous;
     const old = previous.checkpoint;
     if (!await closeLinkRequest(wallet, previous.linkRequestId)) {
@@ -3078,12 +3128,17 @@ var CheckoutClient = class {
         ...signal ? { signal } : {}
       });
     }
-    return __privateMethod(this, _CheckoutClient_instances, linkCardFor_fn).call(this, checkpoint, wallet, linkApprovalTimeoutMs, signal);
+    return __privateMethod(this, _CheckoutClient_instances, linkCardFor_fn).call(this, checkpoint, wallet, {
+      linkApprovalTimeoutMs,
+      signal,
+      onLinkApproval
+    });
   }
 };
 _client4 = new WeakMap();
 _CheckoutClient_instances = new WeakSet();
-linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 * 6e4, signal) {
+linkCardFor_fn = async function(checkpoint, wallet, options) {
+  const { linkApprovalTimeoutMs = 10 * 6e4, signal, onLinkApproval } = options;
   if (checkpoint.stage !== "APPROVED") {
     throw checkoutError(
       `Conto has not approved a card for this checkpoint (stage ${checkpoint.stage}). Do not pay.`,
@@ -3093,6 +3148,7 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
   const deadline = Date.now() + linkApprovalTimeoutMs;
   const call = signal ? { signal } : {};
   let linkRequestId;
+  let approvalUrl;
   let createStarted = false;
   try {
     const cardRequest = linkCardRequest(checkpoint);
@@ -3113,6 +3169,13 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
         message: "Link returned a request for a different amount."
       });
     }
+    if (LINK_WAITING_STATUSES.has(request.status)) {
+      const details = linkApprovalDetails(request);
+      approvalUrl = details.approvalUrl;
+      if (onLinkApproval) {
+        notifyLinkApproval(onLinkApproval, { checkpoint, linkRequestId: request.id, ...details });
+      }
+    }
     while (linkRequestWaiting(request)) {
       const remainingSeconds = Math.floor((deadline - Date.now()) / 1e3);
       if (remainingSeconds <= 0) {
@@ -3127,6 +3190,7 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
         ...call,
         timeoutSeconds: remainingSeconds
       });
+      approvalUrl = LINK_WAITING_STATUSES.has(request.status) ? linkApprovalDetails(request).approvalUrl ?? approvalUrl : void 0;
       if (linkRequestWaiting(request) && Date.now() - started < 1e3) {
         await sleep2(1e3, signal);
       }
@@ -3158,6 +3222,7 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
         code: "LINK_CARD_NOT_CANCELLED",
         checkpoint,
         linkRequestId,
+        ...approvalUrl ? { approvalUrl } : {},
         holdReleased: false,
         retryGuidance: "Retry with the same input to resume this Link request, or cancel it with wallet.cancel(error.linkRequestId) and then call checkout.cancel(error.checkpoint.id)."
       });
@@ -3171,6 +3236,7 @@ linkCardFor_fn = async function(checkpoint, wallet, linkApprovalTimeoutMs = 10 *
       code: failure.code,
       checkpoint,
       ...linkRequestId ? { linkRequestId } : {},
+      ...linkRequestId && approvalUrl ? { approvalUrl } : {},
       holdReleased
     });
   }

package/dist/link-wallet.d.mts

@@ -38,8 +38,13 @@ interface LinkSpendRequest {
     amountMinor?: number;
     merchantName?: string;
     merchantUrl?: string;
-    /** Link page where the person can review the request. */
+    /**
+     * The Stripe Link page where the person can approve the request on the web
+     * while signed in to Link. Only an HTTPS link.com address is kept.
+     */
     approvalUrl?: string;
+    /** When Link stops accepting approval for the request, as an ISO 8601 time. */
+    approvalExpiresAt?: string;
     /** Set with requires_action. `auto_resume` means Link continues once the person finishes the step. */
     actionResolution?: string;
     /** Set with requires_action when Link gives the person a page to finish the step. */

package/dist/link-wallet.d.ts

@@ -38,8 +38,13 @@ interface LinkSpendRequest {
     amountMinor?: number;
     merchantName?: string;
     merchantUrl?: string;
-    /** Link page where the person can review the request. */
+    /**
+     * The Stripe Link page where the person can approve the request on the web
+     * while signed in to Link. Only an HTTPS link.com address is kept.
+     */
     approvalUrl?: string;
+    /** When Link stops accepting approval for the request, as an ISO 8601 time. */
+    approvalExpiresAt?: string;
     /** Set with requires_action. `auto_resume` means Link continues once the person finishes the step. */
     actionResolution?: string;
     /** Set with requires_action when Link gives the person a page to finish the step. */

package/dist/link-wallet.js

@@ -40,6 +40,34 @@ var import_node_fs = require("fs");
 var import_promises = require("fs/promises");
 var import_node_os = require("os");
 var import_node_path = __toESM(require("path"));
+
+// src/link-approval.ts
+function safeLinkApprovalUrl(value) {
+  if (typeof value !== "string" || value.length === 0 || value.length > 2048) return void 0;
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return void 0;
+  }
+  if (url.protocol !== "https:" || url.username !== "" || url.password !== "" || url.port !== "" || !(url.hostname === "link.com" || url.hostname.endsWith(".link.com"))) {
+    return void 0;
+  }
+  url.hash = "";
+  return url.toString();
+}
+function linkTime(value) {
+  let ms = Number.NaN;
+  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+    ms = value < 1e12 ? value * 1e3 : value;
+  } else if (typeof value === "string" && value.length > 0 && value.length <= 64) {
+    ms = Date.parse(value);
+  }
+  const date = new Date(ms);
+  return Number.isNaN(date.getTime()) ? void 0 : date.toISOString();
+}
+
+// src/link-wallet.ts
 var LinkWalletError = class extends Error {
   constructor(reason, message, linkCode) {
     super(message);
@@ -102,13 +130,16 @@ function parseSpendRequest(value) {
   const status = typeof data.status === "string" && KNOWN_STATUSES.has(data.status) ? data.status : "unknown";
   const nextAction = record(record(record(data.status_details).requires_action).next_action);
   const amount = data.amount;
+  const approvalUrl = safeLinkApprovalUrl(data.approval_url);
+  const approvalExpiresAt = linkTime(data.approval_window_expires_at);
   return {
     id,
     status,
     ...Number.isSafeInteger(amount) ? { amountMinor: amount } : {},
     ...text(data.merchant_name) ? { merchantName: text(data.merchant_name) } : {},
     ...httpsUrl(data.merchant_url) ? { merchantUrl: httpsUrl(data.merchant_url) } : {},
-    ...httpsUrl(data.approval_url) ? { approvalUrl: httpsUrl(data.approval_url) } : {},
+    ...approvalUrl ? { approvalUrl } : {},
+    ...approvalExpiresAt ? { approvalExpiresAt } : {},
     ...text(nextAction.resolution) ? { actionResolution: text(nextAction.resolution) } : {},
     ...httpsUrl(nextAction.action_url) ? { actionUrl: httpsUrl(nextAction.action_url) } : {}
   };
@@ -116,15 +147,6 @@ function parseSpendRequest(value) {
 function invalidCard() {
   return new LinkWalletError("invalid_response", "Link returned card data this SDK cannot read.");
 }
-function validUntil(value) {
-  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
-    return new Date(value < 1e12 ? value * 1e3 : value).toISOString();
-  }
-  if (typeof value === "string" && !Number.isNaN(Date.parse(value))) {
-    return new Date(value).toISOString();
-  }
-  return void 0;
-}
 function parseCard(value) {
   const card = record(value);
   const number = typeof card.number === "string" ? card.number.replace(/[\s-]/g, "") : "";
@@ -136,7 +158,7 @@ function parseCard(value) {
   if (!/^\d{12,19}$/.test(number) || !/^\d{3,4}$/.test(securityValue) || !Number.isInteger(expMonth) || expMonth < 1 || expMonth > 12 || !Number.isInteger(expYear) || expYear < 2e3) {
     throw invalidCard();
   }
-  const until = validUntil(card.valid_until);
+  const until = linkTime(card.valid_until);
   const brand = text(card.brand);
   return {
     number,

package/dist/link-wallet.mjs

@@ -1,3 +1,7 @@
+import {
+  linkTime,
+  safeLinkApprovalUrl
+} from "./chunk-PVMUL3JC.mjs";
 import "./chunk-TGOYFBKZ.mjs";
 
 // src/link-wallet.ts
@@ -68,13 +72,16 @@ function parseSpendRequest(value) {
   const status = typeof data.status === "string" && KNOWN_STATUSES.has(data.status) ? data.status : "unknown";
   const nextAction = record(record(record(data.status_details).requires_action).next_action);
   const amount = data.amount;
+  const approvalUrl = safeLinkApprovalUrl(data.approval_url);
+  const approvalExpiresAt = linkTime(data.approval_window_expires_at);
   return {
     id,
     status,
     ...Number.isSafeInteger(amount) ? { amountMinor: amount } : {},
     ...text(data.merchant_name) ? { merchantName: text(data.merchant_name) } : {},
     ...httpsUrl(data.merchant_url) ? { merchantUrl: httpsUrl(data.merchant_url) } : {},
-    ...httpsUrl(data.approval_url) ? { approvalUrl: httpsUrl(data.approval_url) } : {},
+    ...approvalUrl ? { approvalUrl } : {},
+    ...approvalExpiresAt ? { approvalExpiresAt } : {},
     ...text(nextAction.resolution) ? { actionResolution: text(nextAction.resolution) } : {},
     ...httpsUrl(nextAction.action_url) ? { actionUrl: httpsUrl(nextAction.action_url) } : {}
   };
@@ -82,15 +89,6 @@ function parseSpendRequest(value) {
 function invalidCard() {
   return new LinkWalletError("invalid_response", "Link returned card data this SDK cannot read.");
 }
-function validUntil(value) {
-  if (typeof value === "number" && Number.isFinite(value) && value > 0) {
-    return new Date(value < 1e12 ? value * 1e3 : value).toISOString();
-  }
-  if (typeof value === "string" && !Number.isNaN(Date.parse(value))) {
-    return new Date(value).toISOString();
-  }
-  return void 0;
-}
 function parseCard(value) {
   const card = record(value);
   const number = typeof card.number === "string" ? card.number.replace(/[\s-]/g, "") : "";
@@ -102,7 +100,7 @@ function parseCard(value) {
   if (!/^\d{12,19}$/.test(number) || !/^\d{3,4}$/.test(securityValue) || !Number.isInteger(expMonth) || expMonth < 1 || expMonth > 12 || !Number.isInteger(expYear) || expYear < 2e3) {
     throw invalidCard();
   }
-  const until = validUntil(card.valid_until);
+  const until = linkTime(card.valid_until);
   const brand = text(card.brand);
   return {
     number,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conto_finance/sdk",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Conto SDK for AI agent payment authorization",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",