@phala/pay-server 0.13.5 → 0.13.6

package/README.md

@@ -223,3 +223,26 @@ npm (environment `npm`) with trusted publishing and provenance
 [CHANGELOG.md](https://github.com/Phala-Network/phala-pay/blob/main/CHANGELOG.md), under "JS SDK";
 [its releases before v0.5.0](https://github.com/Phala-Network/phala-pay/blob/main/sdk/js/CHANGELOG.md),
 versioned on their own, stay in `sdk/js`.
+
+## Requesting a quote check
+
+`await pay.quotes.check(quoteId)` requests an immediate read-only discovery pass for an open,
+unexpired quote's issued address. Quiet 202 receipt acknowledges the request only; keep normal
+polling/webhook crediting. Checks permit three/quote/rolling day, 15-second address spacing and
+a separate per-chain daily budget. Concurrent requests coalesce; exhaustion leaves normal scanning
+running.
+
+## Receipt helpers
+
+`@phala/pay-server/helpers` exports `stripeReceiptInvoice(deposit, { customer, description? })`,
+`stripeReceiptInvoiceItem(deposit, { invoice, customer })`, and
+`stripeReceiptCreditNote(deposit, { invoice, previousRefunded, previousReversed })`.
+They return typed plain Stripe parameters for a credited `Deposit` (`ReceiptDeposit` subset),
+without a Stripe dependency. Invoices include transaction hashes, explorer links and live/test
+metadata; credit notes cover new refund/reversal growth only (`null` for no growth). Amounts
+always use the deposit currency. Use the official `stripe` library from a queue and persist one
+invoice per deposit; see [the receipt flow and examples](../../docs/integration.md#27-receipts).
+
+`transactionUrl(chainId, txHash)` and `addressUrl(chainId, address)` are available from both
+`@phala/pay-server` and `/helpers`, with the same explorers as `@phala/pay`; they return
+`undefined` for an unknown chain or malformed hash/address.

package/dist/chains.d.ts

@@ -0,0 +1,6 @@
+export declare function networkName(chainId: number): string;
+/** Explorer URL, or undefined for an unknown chain or malformed transaction hash. */
+export declare function transactionUrl(chainId: number, txHash: string): string | undefined;
+/** Explorer URL, or undefined for an unknown chain or malformed address. */
+export declare function addressUrl(chainId: number, address: string): string | undefined;
+//# sourceMappingURL=chains.d.ts.map

package/dist/chains.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chains.d.ts","sourceRoot":"","sources":["../src/chains.ts"],"names":[],"mappings":"AAIA,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIlF;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAI/E"}

package/dist/chains.js

@@ -0,0 +1,21 @@
+import { mainnet, sepolia, base, baseSepolia } from "viem/chains";
+// The same viem chains as @phala/pay, checked against the browser registry in tests.
+const chains = [mainnet, sepolia, base, baseSepolia];
+export function networkName(chainId) {
+    return chains.find((chain) => chain.id === chainId)?.name ?? `Chain ${chainId}`;
+}
+/** Explorer URL, or undefined for an unknown chain or malformed transaction hash. */
+export function transactionUrl(chainId, txHash) {
+    if (txHash.length !== 66 || !/^0x[0-9a-fA-F]{64}$/.test(txHash))
+        return undefined;
+    const explorer = chains.find((chain) => chain.id === chainId)?.blockExplorers.default.url;
+    return explorer === undefined ? undefined : `${explorer}/tx/${txHash}`;
+}
+/** Explorer URL, or undefined for an unknown chain or malformed address. */
+export function addressUrl(chainId, address) {
+    if (address.length !== 42 || !/^0x[0-9a-fA-F]{40}$/.test(address))
+        return undefined;
+    const explorer = chains.find((chain) => chain.id === chainId)?.blockExplorers.default.url;
+    return explorer === undefined ? undefined : `${explorer}/address/${address}`;
+}
+//# sourceMappingURL=chains.js.map

package/dist/chains.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chains.js","sourceRoot":"","sources":["../src/chains.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAElE,qFAAqF;AACrF,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;AACrD,MAAM,UAAU,WAAW,CAAC,OAAe;IACzC,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,OAAO,CAAC,EAAE,IAAI,IAAI,SAAS,OAAO,EAAE,CAAC;AAClF,CAAC;AAED,qFAAqF;AACrF,MAAM,UAAU,cAAc,CAAC,OAAe,EAAE,MAAc;IAC5D,IAAI,MAAM,CAAC,MAAM,KAAK,EAAE,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAC;IAClF,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,OAAO,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC;IAC1F,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,QAAQ,OAAO,MAAM,EAAE,CAAC;AACzE,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,UAAU,CAAC,OAAe,EAAE,OAAe;IACzD,IAAI,OAAO,CAAC,MAAM,KAAK,EAAE,IAAI,CAAC,qBAAqB,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAC;IACpF,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,KAAK,OAAO,CAAC,EAAE,cAAc,CAAC,OAAO,CAAC,GAAG,CAAC;IAC1F,OAAO,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,QAAQ,YAAY,OAAO,EAAE,CAAC;AAC/E,CAAC"}

package/dist/generated/openapi.d.ts

@@ -531,6 +531,23 @@ export interface paths {
         readonly patch?: never;
         readonly trace?: never;
     };
+    readonly "/v1/quotes/{id}/check": {
+        readonly parameters: {
+            readonly query?: never;
+            readonly header?: never;
+            readonly path?: never;
+            readonly cookie?: never;
+        };
+        readonly get?: never;
+        readonly put?: never;
+        /** Request immediate read-only discovery for an open, unexpired quote's issued address. */
+        readonly post: operations["check_quote"];
+        readonly delete?: never;
+        readonly options?: never;
+        readonly head?: never;
+        readonly patch?: never;
+        readonly trace?: never;
+    };
     readonly "/v1/quotes/{id}/transactions": {
         readonly parameters: {
             readonly query?: never;
@@ -3205,6 +3222,24 @@ export interface components {
              */
             readonly window_start: number;
         };
+        /**
+         * @description Quiet receipt of a check request; poll the quote for actual payment status.
+         * @example {
+         *       "object": "quote_check",
+         *       "status": "received"
+         *     }
+         */
+        readonly QuoteCheck: {
+            /** @description Object discriminator. */
+            readonly object: components["schemas"]["QuoteCheckObject"];
+            /** @description Receipt only; limits and processing outcomes are deliberately not disclosed. */
+            readonly status: components["schemas"]["TransactionSubmissionStatus"];
+        };
+        /**
+         * @description Constant quote-check acknowledgement discriminator.
+         * @enum {string}
+         */
+        readonly QuoteCheckObject: "quote_check";
         /**
          * @description A page of quotes, newest first (<https://docs.stripe.com/api/pagination>).
          * @example {
@@ -7516,6 +7551,36 @@ export interface operations {
             };
         };
     };
+    readonly check_quote: {
+        readonly parameters: {
+            readonly query?: {
+                /** @description Object's browser client secret; omit with a merchant key */
+                readonly client_secret?: string;
+            };
+            readonly header?: never;
+            readonly path: {
+                /** @description Quote identifier */
+                readonly id: string;
+            };
+            readonly cookie?: never;
+        };
+        readonly requestBody?: never;
+        readonly responses: {
+            /** @description Received, including ignored checks. Poll the quote for payment status. */
+            readonly 202: {
+                headers: {
+                    /** @description Tenant data and credentials must never be stored, including errors */
+                    readonly "Cache-Control": "no-store";
+                    /** @description The request's id, `req_…` (https://docs.stripe.com/api/request_ids) */
+                    readonly "Request-Id"?: string;
+                    readonly [name: string]: unknown;
+                };
+                content: {
+                    readonly "application/json": components["schemas"]["QuoteCheck"];
+                };
+            };
+        };
+    };
     readonly submit_quote_transaction: {
         readonly parameters: {
             readonly query?: {