@siglume/direct-request-payment 0.4.7 → 0.4.9

package/dist/index.d.ts

@@ -6,7 +6,11 @@ declare const DIRECT_REQUEST_PAYMENT_RECEIPT_KIND = "sdrp_direct_payment";
 declare const DIRECT_REQUEST_PAYMENT_ALLOWANCE_RECEIPT_KIND = "sdrp_direct_payment_allowance";
 declare const DIRECT_REQUEST_PAYMENT_REFERENCE_TYPE = "sdrp_direct_payment_requirement";
 declare const DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
-declare const DIRECT_REQUEST_PAYMENT_SDK_VERSION = "0.4.7";
+declare const DIRECT_REQUEST_PAYMENT_SDK_VERSION = "0.4.9";
+declare const DIRECT_REQUEST_PAYMENT_STANDARD_SETTLED_STATUS = "settled";
+declare const DIRECT_REQUEST_PAYMENT_METERED_ACCEPTED_STATUS = "pending_settlement";
+declare const DIRECT_REQUEST_PAYMENT_STANDARD_FINALITY = "per_payment_onchain";
+declare const DIRECT_REQUEST_PAYMENT_METERED_FINALITY = "aggregated_onchain_settlement";
 type DirectRequestPaymentCurrency = "JPY" | "USD";
 type DirectRequestPaymentToken = "JPYC" | "USDC";
 type DirectRequestPaymentMeteredPlanType = "micro" | "nano";
@@ -411,6 +415,50 @@ interface DirectRequestPaymentWebhookEvent {
     };
     [key: string]: unknown;
 }
+type DirectPaymentConfirmationKind = "standard_settled" | "metered_usage_accepted" | "metered_batch_settled" | "unknown";
+type DirectPaymentConfirmationUnknownReason = "not_direct_payment_confirmed" | "invalid_metered_settlement_confirmation" | "missing_standard_settlement_fields" | "missing_metered_usage_fields" | "unknown_confirmation_shape";
+interface DirectPaymentStandardSettledClassification {
+    kind: "standard_settled";
+    event: DirectRequestPaymentWebhookEvent;
+    data: DirectRequestPaymentWebhookEvent["data"];
+    requirement_id: string;
+    challenge_hash: string;
+    chain_receipt_id: string;
+    request_hash_v2?: string | null;
+}
+interface DirectPaymentMeteredUsageAcceptedClassification {
+    kind: "metered_usage_accepted";
+    event: DirectRequestPaymentWebhookEvent;
+    data: DirectRequestPaymentWebhookEvent["data"];
+    pricing_band: DirectRequestPaymentMeteredPlanType;
+    requirement_id: string;
+    challenge_hash: string;
+    request_hash_v2?: string | null;
+}
+interface DirectPaymentMeteredBatchSettledClassification {
+    kind: "metered_batch_settled";
+    event: DirectRequestPaymentWebhookEvent;
+    data: DirectRequestPaymentWebhookEvent["data"];
+    pricing_band: DirectRequestPaymentMeteredPlanType;
+    settlement_cadence: "weekly" | "monthly";
+    settlement_batch_id: string;
+    chain_receipt_id: string;
+    usage_event_digest: string;
+    settled_at?: string | null;
+}
+interface DirectPaymentUnknownClassification {
+    kind: "unknown";
+    event: DirectRequestPaymentWebhookEvent;
+    data: DirectRequestPaymentWebhookEvent["data"];
+    reason: DirectPaymentConfirmationUnknownReason;
+    requirement_id?: string | null;
+    settlement_batch_id?: string | null;
+    pricing_band?: string | null;
+    settlement_cadence?: string | null;
+    settlement_status?: string | null;
+    finality?: string | null;
+}
+type DirectPaymentConfirmationClassification = DirectPaymentStandardSettledClassification | DirectPaymentMeteredUsageAcceptedClassification | DirectPaymentMeteredBatchSettledClassification | DirectPaymentUnknownClassification;
 declare class SiglumeDirectRequestPaymentError extends Error {
     constructor(message: string);
 }
@@ -562,6 +610,7 @@ declare function verifyWebhookSignature(signing_secret: string, body: Uint8Array
     now?: number;
 }): Promise<WebhookSignatureVerification>;
 declare function parseDirectRequestPaymentWebhookEvent(payload: unknown): DirectRequestPaymentWebhookEvent;
+declare function classifyDirectPaymentConfirmation(event: DirectRequestPaymentWebhookEvent): DirectPaymentConfirmationClassification;
 declare function verifyDirectRequestPaymentWebhook(signing_secret: string, body: Uint8Array | ArrayBuffer | string | Record<string, unknown>, signature_header: string, options?: {
     tolerance_seconds?: number;
     now?: number;
@@ -574,4 +623,4 @@ declare const verifyExternal402Challenge: typeof verifyDirectRequestPaymentChall
 declare const createExternal402RecurringChallenge: typeof createDirectRequestPaymentRecurringChallenge;
 declare const verifyExternal402RecurringChallenge: typeof verifyDirectRequestPaymentRecurringChallenge;
 
-export { DEFAULT_SIGLUME_API_BASE, DEFAULT_WEBHOOK_TOLERANCE_SECONDS, DIRECT_REQUEST_PAYMENT_ALLOWANCE_RECEIPT_KIND, DIRECT_REQUEST_PAYMENT_CHALLENGE_SCHEME, DIRECT_REQUEST_PAYMENT_MODE, DIRECT_REQUEST_PAYMENT_RECEIPT_KIND, DIRECT_REQUEST_PAYMENT_RECURRING_CHALLENGE_SCHEME, DIRECT_REQUEST_PAYMENT_REFERENCE_TYPE, DIRECT_REQUEST_PAYMENT_SDK_VERSION, type DirectPaymentRequirement, type DirectPaymentRequirementCreateInput, type DirectPaymentVerifyInput, type DirectRequestPaymentBillingPlan, type DirectRequestPaymentBuyerMeteredQuery, type DirectRequestPaymentBuyerMeteredSummary, type DirectRequestPaymentBuyerUsageEvent, type DirectRequestPaymentChallenge, type DirectRequestPaymentChallengeInput, type DirectRequestPaymentCheckoutSetupInput, type DirectRequestPaymentCheckoutSetupResult, DirectRequestPaymentClient, type DirectRequestPaymentClientOptions, type DirectRequestPaymentCurrency, type DirectRequestPaymentListResponse, type DirectRequestPaymentMerchantAccount, type DirectRequestPaymentMerchantBillingMandateInput, DirectRequestPaymentMerchantClient, type DirectRequestPaymentMerchantResponse, type DirectRequestPaymentMerchantSetupInput, type DirectRequestPaymentMeteredListQuery, type DirectRequestPaymentMeteredPlanType, type DirectRequestPaymentMinorAmount, type DirectRequestPaymentProviderMeteredListQuery, type DirectRequestPaymentProviderMeteredQuery, type DirectRequestPaymentProviderMeteredSummary, type DirectRequestPaymentProviderUsageEvent, type DirectRequestPaymentRecurringCadence, type DirectRequestPaymentRecurringChallenge, type DirectRequestPaymentRecurringChallengeInput, type DirectRequestPaymentSettlementBatch, type DirectRequestPaymentToken, type DirectRequestPaymentWebhookEvent, type DirectRequestPaymentWebhookSubscription, type DirectRequestPaymentWebhookSubscriptionInput, HostedCheckoutNotAvailableError, type HostedCheckoutSession, type HostedCheckoutSessionCreateInput, type HostedCheckoutSessionCreateResult, type ParsedDirectRequestPaymentChallenge, SiglumeApiError, SiglumeDirectRequestPaymentError, type SiglumeEnvelopeMeta, SiglumeWebhookPayloadError, SiglumeWebhookSignatureError, type Web3PreparedTransactionExecutePayload, type Web3PreparedTransactionExecuteResult, type Web3TransactionRequest, type WebhookSignatureVerification, buildAllowanceExecutionPayload, buildPaymentExecutionPayload, buildPreparedTransactionExecutionPayload, buildWebhookSignatureHeader, computeWebhookSignature, createDirectRequestPaymentChallenge, createDirectRequestPaymentChallengeSignature, createDirectRequestPaymentRecurringChallenge, createDirectRequestPaymentRecurringChallengeSignature, createExternal402Challenge, createExternal402RecurringChallenge, directRequestPaymentChallengeHash, directRequestPaymentRequestHash, directRequestPaymentRequestHashV2, parseDirectRequestPaymentChallenge, parseDirectRequestPaymentWebhookEvent, verifyDirectRequestPaymentChallenge, verifyDirectRequestPaymentRecurringChallenge, verifyDirectRequestPaymentWebhook, verifyExternal402Challenge, verifyExternal402RecurringChallenge, verifyWebhookSignature };
+export { DEFAULT_SIGLUME_API_BASE, DEFAULT_WEBHOOK_TOLERANCE_SECONDS, DIRECT_REQUEST_PAYMENT_ALLOWANCE_RECEIPT_KIND, DIRECT_REQUEST_PAYMENT_CHALLENGE_SCHEME, DIRECT_REQUEST_PAYMENT_METERED_ACCEPTED_STATUS, DIRECT_REQUEST_PAYMENT_METERED_FINALITY, DIRECT_REQUEST_PAYMENT_MODE, DIRECT_REQUEST_PAYMENT_RECEIPT_KIND, DIRECT_REQUEST_PAYMENT_RECURRING_CHALLENGE_SCHEME, DIRECT_REQUEST_PAYMENT_REFERENCE_TYPE, DIRECT_REQUEST_PAYMENT_SDK_VERSION, DIRECT_REQUEST_PAYMENT_STANDARD_FINALITY, DIRECT_REQUEST_PAYMENT_STANDARD_SETTLED_STATUS, type DirectPaymentConfirmationClassification, type DirectPaymentConfirmationKind, type DirectPaymentConfirmationUnknownReason, type DirectPaymentMeteredBatchSettledClassification, type DirectPaymentMeteredUsageAcceptedClassification, type DirectPaymentRequirement, type DirectPaymentRequirementCreateInput, type DirectPaymentStandardSettledClassification, type DirectPaymentUnknownClassification, type DirectPaymentVerifyInput, type DirectRequestPaymentBillingPlan, type DirectRequestPaymentBuyerMeteredQuery, type DirectRequestPaymentBuyerMeteredSummary, type DirectRequestPaymentBuyerUsageEvent, type DirectRequestPaymentChallenge, type DirectRequestPaymentChallengeInput, type DirectRequestPaymentCheckoutSetupInput, type DirectRequestPaymentCheckoutSetupResult, DirectRequestPaymentClient, type DirectRequestPaymentClientOptions, type DirectRequestPaymentCurrency, type DirectRequestPaymentListResponse, type DirectRequestPaymentMerchantAccount, type DirectRequestPaymentMerchantBillingMandateInput, DirectRequestPaymentMerchantClient, type DirectRequestPaymentMerchantResponse, type DirectRequestPaymentMerchantSetupInput, type DirectRequestPaymentMeteredListQuery, type DirectRequestPaymentMeteredPlanType, type DirectRequestPaymentMinorAmount, type DirectRequestPaymentProviderMeteredListQuery, type DirectRequestPaymentProviderMeteredQuery, type DirectRequestPaymentProviderMeteredSummary, type DirectRequestPaymentProviderUsageEvent, type DirectRequestPaymentRecurringCadence, type DirectRequestPaymentRecurringChallenge, type DirectRequestPaymentRecurringChallengeInput, type DirectRequestPaymentSettlementBatch, type DirectRequestPaymentToken, type DirectRequestPaymentWebhookEvent, type DirectRequestPaymentWebhookSubscription, type DirectRequestPaymentWebhookSubscriptionInput, HostedCheckoutNotAvailableError, type HostedCheckoutSession, type HostedCheckoutSessionCreateInput, type HostedCheckoutSessionCreateResult, type ParsedDirectRequestPaymentChallenge, SiglumeApiError, SiglumeDirectRequestPaymentError, type SiglumeEnvelopeMeta, SiglumeWebhookPayloadError, SiglumeWebhookSignatureError, type Web3PreparedTransactionExecutePayload, type Web3PreparedTransactionExecuteResult, type Web3TransactionRequest, type WebhookSignatureVerification, buildAllowanceExecutionPayload, buildPaymentExecutionPayload, buildPreparedTransactionExecutionPayload, buildWebhookSignatureHeader, classifyDirectPaymentConfirmation, computeWebhookSignature, createDirectRequestPaymentChallenge, createDirectRequestPaymentChallengeSignature, createDirectRequestPaymentRecurringChallenge, createDirectRequestPaymentRecurringChallengeSignature, createExternal402Challenge, createExternal402RecurringChallenge, directRequestPaymentChallengeHash, directRequestPaymentRequestHash, directRequestPaymentRequestHashV2, parseDirectRequestPaymentChallenge, parseDirectRequestPaymentWebhookEvent, verifyDirectRequestPaymentChallenge, verifyDirectRequestPaymentRecurringChallenge, verifyDirectRequestPaymentWebhook, verifyExternal402Challenge, verifyExternal402RecurringChallenge, verifyWebhookSignature };

package/dist/index.js

@@ -7,7 +7,11 @@ var DIRECT_REQUEST_PAYMENT_RECEIPT_KIND = "sdrp_direct_payment";
 var DIRECT_REQUEST_PAYMENT_ALLOWANCE_RECEIPT_KIND = "sdrp_direct_payment_allowance";
 var DIRECT_REQUEST_PAYMENT_REFERENCE_TYPE = "sdrp_direct_payment_requirement";
 var DEFAULT_WEBHOOK_TOLERANCE_SECONDS = 300;
-var DIRECT_REQUEST_PAYMENT_SDK_VERSION = "0.4.7";
+var DIRECT_REQUEST_PAYMENT_SDK_VERSION = "0.4.9";
+var DIRECT_REQUEST_PAYMENT_STANDARD_SETTLED_STATUS = "settled";
+var DIRECT_REQUEST_PAYMENT_METERED_ACCEPTED_STATUS = "pending_settlement";
+var DIRECT_REQUEST_PAYMENT_STANDARD_FINALITY = "per_payment_onchain";
+var DIRECT_REQUEST_PAYMENT_METERED_FINALITY = "aggregated_onchain_settlement";
 var DIRECT_REQUEST_PAYMENT_CONFIRMED_WEBHOOK_MODES = /* @__PURE__ */ new Set([DIRECT_REQUEST_PAYMENT_MODE, "metered_settlement_batch"]);
 var SiglumeDirectRequestPaymentError = class extends Error {
   constructor(message) {
@@ -600,6 +604,120 @@ function parseDirectRequestPaymentWebhookEvent(payload) {
   }
   return parsed;
 }
+function classifyDirectPaymentConfirmation(event) {
+  const data = event.data;
+  const requirementId = stringOrNull(data.requirement_id) ?? stringOrNull(data.direct_payment_requirement_id);
+  const challengeHash = stringOrNull(data.challenge_hash);
+  const pricingBand = stringOrNull(data.pricing_band);
+  const settlementCadence = stringOrNull(data.settlement_cadence);
+  const finality = stringOrNull(data.finality);
+  const settlementStatus = stringOrNull(data.settlement_status);
+  if (event.type !== "direct_payment.confirmed") {
+    return {
+      kind: "unknown",
+      event,
+      data,
+      reason: "not_direct_payment_confirmed",
+      requirement_id: requirementId,
+      settlement_batch_id: stringOrNull(data.settlement_batch_id),
+      pricing_band: pricingBand,
+      settlement_cadence: settlementCadence,
+      settlement_status: settlementStatus,
+      finality
+    };
+  }
+  if (data.mode === "metered_settlement_batch") {
+    const settlementBatchId = stringOrNull(data.settlement_batch_id);
+    const chainReceiptId = stringOrNull(data.chain_receipt_id);
+    const usageEventDigest = stringOrNull(data.usage_event_digest);
+    if (settlementStatus === DIRECT_REQUEST_PAYMENT_STANDARD_SETTLED_STATUS && finality === DIRECT_REQUEST_PAYMENT_METERED_FINALITY && (pricingBand === "micro" || pricingBand === "nano") && settlementCadence === (pricingBand === "micro" ? "weekly" : "monthly") && settlementBatchId && chainReceiptId && usageEventDigest) {
+      return {
+        kind: "metered_batch_settled",
+        event,
+        data,
+        pricing_band: pricingBand,
+        settlement_cadence: pricingBand === "micro" ? "weekly" : "monthly",
+        settlement_batch_id: settlementBatchId,
+        chain_receipt_id: chainReceiptId,
+        usage_event_digest: usageEventDigest,
+        settled_at: stringOrNull(data.settled_at)
+      };
+    }
+    return {
+      kind: "unknown",
+      event,
+      data,
+      reason: "invalid_metered_settlement_confirmation",
+      requirement_id: requirementId,
+      settlement_batch_id: settlementBatchId,
+      pricing_band: pricingBand,
+      settlement_cadence: settlementCadence,
+      settlement_status: settlementStatus,
+      finality
+    };
+  }
+  if (pricingBand === "standard") {
+    const chainReceiptId = stringOrNull(data.chain_receipt_id);
+    if (finality === DIRECT_REQUEST_PAYMENT_STANDARD_FINALITY && settlementStatus === DIRECT_REQUEST_PAYMENT_STANDARD_SETTLED_STATUS && requirementId && challengeHash && chainReceiptId) {
+      return {
+        kind: "standard_settled",
+        event,
+        data,
+        requirement_id: requirementId,
+        challenge_hash: challengeHash,
+        chain_receipt_id: chainReceiptId,
+        request_hash_v2: stringOrNull(data.request_hash_v2)
+      };
+    }
+    return {
+      kind: "unknown",
+      event,
+      data,
+      reason: "missing_standard_settlement_fields",
+      requirement_id: requirementId,
+      pricing_band: pricingBand,
+      settlement_cadence: settlementCadence,
+      settlement_status: settlementStatus,
+      finality
+    };
+  }
+  if (pricingBand === "micro" || pricingBand === "nano") {
+    if (finality === DIRECT_REQUEST_PAYMENT_METERED_FINALITY && settlementStatus === DIRECT_REQUEST_PAYMENT_METERED_ACCEPTED_STATUS && requirementId && challengeHash) {
+      return {
+        kind: "metered_usage_accepted",
+        event,
+        data,
+        pricing_band: pricingBand,
+        requirement_id: requirementId,
+        challenge_hash: challengeHash,
+        request_hash_v2: stringOrNull(data.request_hash_v2)
+      };
+    }
+    return {
+      kind: "unknown",
+      event,
+      data,
+      reason: "missing_metered_usage_fields",
+      requirement_id: requirementId,
+      pricing_band: pricingBand,
+      settlement_cadence: settlementCadence,
+      settlement_status: settlementStatus,
+      finality
+    };
+  }
+  return {
+    kind: "unknown",
+    event,
+    data,
+    reason: "unknown_confirmation_shape",
+    requirement_id: requirementId,
+    settlement_batch_id: stringOrNull(data.settlement_batch_id),
+    pricing_band: pricingBand,
+    settlement_cadence: settlementCadence,
+    settlement_status: settlementStatus,
+    finality
+  };
+}
 async function verifyDirectRequestPaymentWebhook(signing_secret, body, signature_header, options = {}) {
   const verification = await verifyWebhookSignature(signing_secret, body, signature_header, options);
   const text = new TextDecoder().decode(bodyBytes(body));
@@ -948,11 +1066,15 @@ export {
   DEFAULT_WEBHOOK_TOLERANCE_SECONDS,
   DIRECT_REQUEST_PAYMENT_ALLOWANCE_RECEIPT_KIND,
   DIRECT_REQUEST_PAYMENT_CHALLENGE_SCHEME,
+  DIRECT_REQUEST_PAYMENT_METERED_ACCEPTED_STATUS,
+  DIRECT_REQUEST_PAYMENT_METERED_FINALITY,
   DIRECT_REQUEST_PAYMENT_MODE,
   DIRECT_REQUEST_PAYMENT_RECEIPT_KIND,
   DIRECT_REQUEST_PAYMENT_RECURRING_CHALLENGE_SCHEME,
   DIRECT_REQUEST_PAYMENT_REFERENCE_TYPE,
   DIRECT_REQUEST_PAYMENT_SDK_VERSION,
+  DIRECT_REQUEST_PAYMENT_STANDARD_FINALITY,
+  DIRECT_REQUEST_PAYMENT_STANDARD_SETTLED_STATUS,
   DirectRequestPaymentClient,
   DirectRequestPaymentMerchantClient,
   HostedCheckoutNotAvailableError,
@@ -964,6 +1086,7 @@ export {
   buildPaymentExecutionPayload,
   buildPreparedTransactionExecutionPayload,
   buildWebhookSignatureHeader,
+  classifyDirectPaymentConfirmation,
   computeWebhookSignature,
   createDirectRequestPaymentChallenge,
   createDirectRequestPaymentChallengeSignature,