@dvmkit/sdk 0.1.2-rc.7 → 0.1.3-rc.7
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 +14 -0
- package/dist/chunk-2K7E3N2D.js +1709 -0
- package/dist/{chunk-N4VTG3KH.js → chunk-3ZHMQCYP.js} +645 -3027
- package/dist/{chunk-TKA6ZP4M.js → chunk-4B56DEEV.js} +50 -426
- package/dist/chunk-BIFLRKMO.js +87 -0
- package/dist/chunk-BQ2NMWKE.js +160 -0
- package/dist/{chunk-LDTWX7JW.js → chunk-BTZY7VPH.js} +13 -1
- package/dist/{chunk-FJDCFHW5.js → chunk-C6JHBLMW.js} +3 -81
- package/dist/{chunk-EXHBXA4U.js → chunk-DBCLBYHP.js} +13 -1
- package/dist/chunk-EPNDZ5DH.js +1010 -0
- package/dist/{chunk-P4RUVDU7.js → chunk-H2MEFVH6.js} +12 -141
- package/dist/chunk-KXZUCCEY.js +142 -0
- package/dist/{chunk-6JZIX5WW.js → chunk-LLXV32HA.js} +82 -5
- package/dist/{chunk-LWUR4CGG.js → chunk-MLRCSJYX.js} +11 -3
- package/dist/{chunk-2ABMGUDS.js → chunk-NFRM5QYP.js} +83 -10
- package/dist/chunk-RW5LP57K.js +44 -0
- package/dist/chunk-YDIYXGYL.js +384 -0
- package/dist/{chunk-JGGI65I3.js → chunk-Z4BNLUZF.js} +1 -150
- package/dist/{credit-ledger-ED6JXKVD.js → credit-ledger-2DFQHNLB.js} +2 -2
- package/dist/{credit-menu-BM4qCD5U.d.ts → credit-menu-C7zAJElJ.d.ts} +1632 -1946
- package/dist/{fx-C-liI3oY.d.ts → fx-BF_SG2i0.d.ts} +1 -1
- package/dist/index.d.ts +7 -6
- package/dist/index.js +8 -4
- package/dist/internal/caller.d.ts +10429 -0
- package/dist/internal/caller.js +9957 -0
- package/dist/internal/index.d.ts +2 -10816
- package/dist/internal/index.js +2 -10130
- package/dist/internal/server.d.ts +404 -0
- package/dist/internal/server.js +202 -0
- package/dist/job-store-Bn23V3QU.d.ts +576 -0
- package/dist/lightning-backend-C04nH94l.d.ts +367 -0
- package/dist/{memory-credit-ledger-XJ5VQEVP.js → memory-credit-ledger-OP24Z2KO.js} +3 -3
- package/dist/{postgres-job-store-J5F4GUWU.js → postgres-job-store-TAONYLIF.js} +1 -1
- package/dist/{revenue-reporter-JIKUPXOK.js → revenue-reporter-XXSU5KVB.js} +1 -1
- package/dist/server/index.d.ts +27 -11
- package/dist/server/index.js +93 -69
- package/dist/{job-store-C53VQ5uu.d.ts → step-cache-3cT4Shk0.d.ts} +31 -585
- package/dist/{tempo-session-store-DALMRIWN.js → tempo-session-store-2JNOKJGX.js} +2 -2
- package/dist/testing/index.d.ts +16 -4
- package/dist/testing/index.js +7 -3
- package/dist/{usd-gLcJB1ps.d.ts → usd-BnuXoFl5.d.ts} +1 -1
- package/dist/wallet-CJC8lwxx.d.ts +29 -0
- package/dist/{x402-FTG2GRAQ.js → x402-T2C5MX3T.js} +6 -3
- package/package.json +6 -2
- package/dist/{chunk-RU7SXHLO.js → chunk-UP2F5RRT.js} +3 -3
|
@@ -1,12 +1,11 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { MiddlewareHandler, Context, Hono } from 'hono';
|
|
2
2
|
import { Challenge, Credential, Store, Method, Receipt } from 'mppx';
|
|
3
|
-
import { FacilitatorClient
|
|
3
|
+
import { FacilitatorClient } from '@x402/core/server';
|
|
4
4
|
import { AuthorizerSigner, ChannelStorage, AutoSettlementConfig, Channel, ChannelUpdateResult } from '@x402/evm/batch-settlement/server';
|
|
5
|
-
import { MiddlewareHandler, Context, Hono } from 'hono';
|
|
6
5
|
import { Account, Client, Hex } from 'viem';
|
|
7
6
|
import { Pool, PoolClient } from 'pg';
|
|
8
|
-
import { PaymentPayload as PaymentPayload$1, PaymentRequirements as PaymentRequirements$1, SettleResponse as SettleResponse$1 } from '@x402/core/types';
|
|
9
7
|
import { z } from 'zod';
|
|
8
|
+
import { PaymentPayload as PaymentPayload$1, PaymentRequirements as PaymentRequirements$1, SettleResponse as SettleResponse$1 } from '@x402/core/types';
|
|
10
9
|
|
|
11
10
|
/**
|
|
12
11
|
* Currency-code identifier used throughout the SDK's pricing surface. Validated
|
|
@@ -415,19 +414,6 @@ declare function exactEvmAuthorization(payload: PaymentPayload): ExactEvmPayload
|
|
|
415
414
|
* x402 spec).
|
|
416
415
|
*/
|
|
417
416
|
declare function encodeSettleResponseHeader(response: SettleResponse): string;
|
|
418
|
-
/**
|
|
419
|
-
* POST a verify request to the facilitator. Returns the parsed `VerifyResponse`
|
|
420
|
-
* or a structured-failure shape when the facilitator rejects the call (network
|
|
421
|
-
* error, non-2xx, or `isValid: false`).
|
|
422
|
-
*/
|
|
423
|
-
declare function verifyWithFacilitator(payload: PaymentPayload, requirements: PaymentRequirementsV1 | PaymentRequirementsV2, config?: Pick<X402Config, "facilitator" | "facilitatorAuth">, createAuthHeaders?: FacilitatorConfig["createAuthHeaders"] | undefined): Promise<VerifyResponse>;
|
|
424
|
-
/**
|
|
425
|
-
* POST a settle request to the facilitator. The facilitator broadcasts the
|
|
426
|
-
* EIP-3009 `transferWithAuthorization` and returns the on-chain tx hash on
|
|
427
|
-
* success; the dvmkit DVM mirrors that into `X-PAYMENT-RESPONSE` for the
|
|
428
|
-
* client and into `revenue_events.tx_hash` for the platform ledger.
|
|
429
|
-
*/
|
|
430
|
-
declare function settleWithFacilitator(payload: PaymentPayload, requirements: PaymentRequirementsV1 | PaymentRequirementsV2, config?: Pick<X402Config, "facilitator" | "facilitatorAuth">, createAuthHeaders?: FacilitatorConfig["createAuthHeaders"] | undefined): Promise<SettleResponse>;
|
|
431
417
|
|
|
432
418
|
/** Identifies which side of the conversation sent a message. */
|
|
433
419
|
type MessageFrom = "requester" | "provider";
|
|
@@ -1649,7 +1635,7 @@ declare class PayoutReporter implements PayoutTransport {
|
|
|
1649
1635
|
|
|
1650
1636
|
/**
|
|
1651
1637
|
* JSON wire shape POSTed to the platform's `/_internal/job-revenue` endpoint
|
|
1652
|
-
* and stored in `
|
|
1638
|
+
* and stored in `pending_dvm_reports.payload` for durable retry.
|
|
1653
1639
|
*
|
|
1654
1640
|
* The platform-side consumer is `OnJobCompleted`, implemented by
|
|
1655
1641
|
* `createRevenueCallback`. Keep the two shapes in sync: the SDK and platform
|
|
@@ -1741,6 +1727,8 @@ interface CreditDepositPayload {
|
|
|
1741
1727
|
dvmId: string;
|
|
1742
1728
|
/** Required. Credit the funding landed on. */
|
|
1743
1729
|
creditId: string;
|
|
1730
|
+
/** Required. Canonical owner of the funded credit. */
|
|
1731
|
+
callerPubkey: string;
|
|
1744
1732
|
/** Required. The rail's settlement reference — the deposit's idempotency key. */
|
|
1745
1733
|
fundingId: string;
|
|
1746
1734
|
/** Required. Payment rail (`"cashu"`, `"tempo"`, `"x402"`). */
|
|
@@ -1865,6 +1853,8 @@ interface CreditDrainPayload {
|
|
|
1865
1853
|
dvmId: string;
|
|
1866
1854
|
/** Required. Credit the reclaim came off. */
|
|
1867
1855
|
creditId: string;
|
|
1856
|
+
/** Required. Canonical owner of the reclaimed credit. */
|
|
1857
|
+
callerPubkey: string;
|
|
1868
1858
|
/** Required. The drain's own idempotency key. */
|
|
1869
1859
|
drainId: string;
|
|
1870
1860
|
/** Required. Payout rail the reclaim shipped on (`"cashu"`, `"x402"`, `"tempo"`). */
|
|
@@ -2107,10 +2097,16 @@ declare class RevenueReporter {
|
|
|
2107
2097
|
private static readonly MAX_BACKOFF_MS;
|
|
2108
2098
|
private static readonly ABANDON_AFTER_MS;
|
|
2109
2099
|
constructor(db: Pool, platformUrl: string, platformToken: string);
|
|
2110
|
-
/** Create the pending-reports table (idempotent). */
|
|
2100
|
+
/** Create the pending-reports table and migrate the legacy SDK outbox (idempotent). */
|
|
2111
2101
|
init(): Promise<void>;
|
|
2112
2102
|
/** The boot DDL itself — always runs under {@link withSdkInitLock} (internal-review). */
|
|
2113
2103
|
private createTables;
|
|
2104
|
+
/** Copy rows from the old SDK-owned table without touching the platform's table of that name. */
|
|
2105
|
+
private migrateLegacySdkOutbox;
|
|
2106
|
+
/** Refuse a pre-existing relation whose columns cannot safely serve as the SDK outbox. */
|
|
2107
|
+
private assertSdkTableShape;
|
|
2108
|
+
private assertSdkColumns;
|
|
2109
|
+
private tableColumns;
|
|
2114
2110
|
/** Persist a revenue report and attempt immediate delivery. */
|
|
2115
2111
|
report(payload: RevenueReportPayload): Promise<void>;
|
|
2116
2112
|
/**
|
|
@@ -3357,6 +3353,8 @@ declare class CreditLedger {
|
|
|
3357
3353
|
}): Promise<DrawRecord | undefined>;
|
|
3358
3354
|
/** Read the sole draw bound to a pre-allocated job id; ambiguity fails closed. */
|
|
3359
3355
|
getDrawByJobId(jobId: string): Promise<DrawRecord | undefined>;
|
|
3356
|
+
/** Read every draw linked to a job, including already-resolved rows. */
|
|
3357
|
+
listDrawsByJobId(jobId: string): Promise<DrawRecord[]>;
|
|
3360
3358
|
/**
|
|
3361
3359
|
* All pending holds on a credit, in `ledger_seq` order (no lock). Read
|
|
3362
3360
|
* surface for the internal-review sweeper wiring — a worker that dies mid-job
|
|
@@ -3936,6 +3934,8 @@ interface CreditLedgerLike {
|
|
|
3936
3934
|
}): Promise<DrawRecord | undefined>;
|
|
3937
3935
|
/** Read the sole draw linked to a stable pre-payment job id. */
|
|
3938
3936
|
getDrawByJobId(jobId: string): Promise<DrawRecord | undefined>;
|
|
3937
|
+
/** Read every draw linked to a job so retention can resolve all holds before redaction. */
|
|
3938
|
+
listDrawsByJobId(jobId: string): Promise<DrawRecord[]>;
|
|
3939
3939
|
listPendingDraws(creditId: string): Promise<DrawRecord[]>;
|
|
3940
3940
|
listStalePendingDraws(args: {
|
|
3941
3941
|
createdBeforeMs: number;
|
|
@@ -5963,6 +5963,8 @@ declare const DEFAULT_CREDIT_MIN: PriceValue;
|
|
|
5963
5963
|
declare const DEFAULT_CREDIT_MAX: PriceValue;
|
|
5964
5964
|
/** Platform default for {@link CreditConfig.ttl} — 30 days (credits spec §15, ratified). */
|
|
5965
5965
|
declare const DEFAULT_CREDIT_TTL_SECONDS: number;
|
|
5966
|
+
/** Default lifetime of caller-controlled job content before it is redacted. */
|
|
5967
|
+
declare const DEFAULT_JOB_RETENTION_DAYS = 90;
|
|
5966
5968
|
/**
|
|
5967
5969
|
* Per-capability configuration for the multi-capability shape (internal-review).
|
|
5968
5970
|
* Each capability is an independent unit a caller pays for: its own input
|
|
@@ -6128,6 +6130,13 @@ interface DVMConfig<State = Record<string, unknown>, InputSchema extends ZodLike
|
|
|
6128
6130
|
* event loop synchronously for longer than the heartbeat interval.
|
|
6129
6131
|
*/
|
|
6130
6132
|
processingWatchdog?: number;
|
|
6133
|
+
/**
|
|
6134
|
+
* Days terminal job content remains available before the SDK redacts it.
|
|
6135
|
+
* The durable row, payment linkage, and signed receipt remain for accounting
|
|
6136
|
+
* and request-id safety. Default: 90. Set to `0` to disable automatic
|
|
6137
|
+
* redaction.
|
|
6138
|
+
*/
|
|
6139
|
+
jobRetentionDays?: number;
|
|
6131
6140
|
/**
|
|
6132
6141
|
* Descriptor-level auth scheme (internal-review). Fires on `/v1/job` and
|
|
6133
6142
|
* `/v1/quote` before payment verification and handler dispatch — unsigned
|
|
@@ -6235,6 +6244,8 @@ interface DVMDescriptor<State = Record<string, unknown>, InputSchema extends Zod
|
|
|
6235
6244
|
readonly idleTimeout: number;
|
|
6236
6245
|
/** Seconds before a worker-stranded `processing`/`working` job is marked `failed` (internal-review). Undefined → SDK default (5 min). */
|
|
6237
6246
|
readonly processingWatchdog?: number;
|
|
6247
|
+
/** Days terminal job content is retained; `0` disables automatic redaction. */
|
|
6248
|
+
readonly jobRetentionDays: number;
|
|
6238
6249
|
/** Reference to the original DVMConfig (handler functions, quote config, etc.). */
|
|
6239
6250
|
readonly config: DVMConfig<State, InputSchema>;
|
|
6240
6251
|
/**
|
|
@@ -6298,569 +6309,4 @@ declare class StepCache {
|
|
|
6298
6309
|
static deserialize(records: StepRecord[]): StepCache;
|
|
6299
6310
|
}
|
|
6300
6311
|
|
|
6301
|
-
|
|
6302
|
-
type JobStatus = "processing" | "completed" | "failed" | "awaiting-input" | "cancelled" | "working";
|
|
6303
|
-
/** Serializable snapshot of a job's persistent state. */
|
|
6304
|
-
interface JobRecord {
|
|
6305
|
-
id: string;
|
|
6306
|
-
tags: string[];
|
|
6307
|
-
/**
|
|
6308
|
-
* Capability name this job dispatches to (internal-review). Populated from the
|
|
6309
|
-
* `POST /v1/job` body's `capability` field at submission time; persisted
|
|
6310
|
-
* so reactivation on another machine routes to the same handler.
|
|
6311
|
-
*/
|
|
6312
|
-
capability: string;
|
|
6313
|
-
input: string;
|
|
6314
|
-
params: Record<string, string>;
|
|
6315
|
-
requesterId: string;
|
|
6316
|
-
/**
|
|
6317
|
-
* SHA-256 hex of the per-job opaque token issued at creation time for
|
|
6318
|
-
* anonymous requesters (internal-review). When set, all `/v1/job/:id/*` reads/writes
|
|
6319
|
-
* gate on the caller presenting the matching `X-Job-Token` header — this is
|
|
6320
|
-
* the mechanism that prevents cross-caller transcript leaks for free DVMs
|
|
6321
|
-
* where every caller otherwise resolves to `requesterId === "anonymous"`.
|
|
6322
|
-
* Undefined for authenticated jobs (bearer / signed-request), which gate on
|
|
6323
|
-
* `requesterId` instead.
|
|
6324
|
-
*/
|
|
6325
|
-
requesterTokenHash?: string;
|
|
6326
|
-
/**
|
|
6327
|
-
* The `job_token` itself, in the clear (internal-review). Kept so a caller whose
|
|
6328
|
-
* paid submit timed out can replay it and be handed back the very token the
|
|
6329
|
-
* lost response carried — the alternative (minting a fresh one) would be
|
|
6330
|
-
* rejected by whichever machine is still running the job, since its
|
|
6331
|
-
* `activeJobs` copy holds the original hash.
|
|
6332
|
-
*
|
|
6333
|
-
* The cost is that DB read access now also confers job *control* (cancel,
|
|
6334
|
-
* feed input), not just read access. Accepted: the same database holds the
|
|
6335
|
-
* accumulator's Cashu proofs, which are bearer money — a reader who gets
|
|
6336
|
-
* that far has strictly better targets. `requesterTokenHash` remains the
|
|
6337
|
-
* only thing the ownership check reads.
|
|
6338
|
-
*/
|
|
6339
|
-
requesterToken?: string;
|
|
6340
|
-
/**
|
|
6341
|
-
* Fingerprint of the submission that created this job (internal-review) — see
|
|
6342
|
-
* `requestFingerprint`. The replay gate: a retried paid submit is handed the
|
|
6343
|
-
* original job only when it reproduces this.
|
|
6344
|
-
*/
|
|
6345
|
-
requestFingerprint?: string;
|
|
6346
|
-
/**
|
|
6347
|
-
* secp256k1 x-only pubkey of the caller that signed the submission, on
|
|
6348
|
-
* DVMs with descriptor-level auth (internal-review). Second half of the replay
|
|
6349
|
-
* gate — the signature envelope is re-minted on every resume attempt, so
|
|
6350
|
-
* the identity behind it is pinned here instead.
|
|
6351
|
-
*/
|
|
6352
|
-
requesterPubkey?: string;
|
|
6353
|
-
/** Caller-generated public recovery id bound to this request fingerprint. */
|
|
6354
|
-
requestId?: string;
|
|
6355
|
-
/** HTTP path whose live auth gate accepted the persisted caller proof. */
|
|
6356
|
-
authRequestPath?: string;
|
|
6357
|
-
status: JobStatus;
|
|
6358
|
-
summary?: string;
|
|
6359
|
-
messages: Message[];
|
|
6360
|
-
seq: number;
|
|
6361
|
-
paidMsats: number;
|
|
6362
|
-
paymentMint?: string;
|
|
6363
|
-
/** Rail of the most recent successful credit (cashu / x402 / mpp). */
|
|
6364
|
-
paymentRail?: FundingMethod;
|
|
6365
|
-
/**
|
|
6366
|
-
* Settlement reference threaded into the platform revenue ledger
|
|
6367
|
-
* (`revenue_events.tx_hash`). EVM tx hash for x402, mppx `challenge.id`
|
|
6368
|
-
* for mpp (internal-review); cashu accumulator path sets this to the
|
|
6369
|
-
* `X-Cashu-Request-Id` UUID (internal-review). Persisted so it survives durable
|
|
6370
|
-
* replay.
|
|
6371
|
-
*/
|
|
6372
|
-
paymentTxHash?: string;
|
|
6373
|
-
/** Chain transaction returned to callers recovering x402 or Tempo acceptance. */
|
|
6374
|
-
paymentTransactionHash?: string;
|
|
6375
|
-
/** Rail-native upfront amount (sats / USDC microunits). internal-review. */
|
|
6376
|
-
nativeAmount?: number;
|
|
6377
|
-
/** Native asset tag — paired with `nativeAmount`. internal-review. */
|
|
6378
|
-
nativeAsset?: "sats" | "usdc" | "usdc.e" | "usd-cents";
|
|
6379
|
-
/** Cashu flow discriminator written into `revenue_events.metadata.cashu_flow` (internal-review). */
|
|
6380
|
-
cashuFlow?: "p2pk_accumulator";
|
|
6381
|
-
/**
|
|
6382
|
-
* Credit the upfront payment funded/drew (internal-review). The terminal funnel
|
|
6383
|
-
* settles the draw on success and releases it on failure/cancel, and the
|
|
6384
|
-
* receipt countersigns the `ReceiptCredit` block from it.
|
|
6385
|
-
*/
|
|
6386
|
-
creditId?: string;
|
|
6387
|
-
/** The draw placed for this job on `creditId` (internal-review). */
|
|
6388
|
-
drawId?: string;
|
|
6389
|
-
/** Funding-time evidence returned on explicit fund-and-draw submissions. */
|
|
6390
|
-
fundingReceipt?: FundingReceipt;
|
|
6391
|
-
fundingCredit?: CreditSnapshot;
|
|
6392
|
-
receivedProofs: ProofLike[];
|
|
6393
|
-
pendingPaymentMsats?: number;
|
|
6394
|
-
/**
|
|
6395
|
-
* Per-job MPP credential binding (internal-review). Challenge ids issued in the
|
|
6396
|
-
* most-recent `requestPayment` yield; the SDK rejects mid-job credentials
|
|
6397
|
-
* whose `challenge.id` isn't in this set.
|
|
6398
|
-
*
|
|
6399
|
-
* Keeps its `mpp` spelling past internal-review's rail rename (internal-review). The ids
|
|
6400
|
-
* are mppx challenge ids — objects of the MPP envelope the Tempo rail rides,
|
|
6401
|
-
* which is not itself a rail — and this is server-internal anti-replay state
|
|
6402
|
-
* that is never serialised to a caller. It persists as
|
|
6403
|
-
* `jobs.pending_mpp_challenge_ids` / `isolate_jobs.pending_mpp_challenge_ids`.
|
|
6404
|
-
*/
|
|
6405
|
-
pendingMppChallengeIds?: string[];
|
|
6406
|
-
/**
|
|
6407
|
-
* Per-job x402 credential binding (internal-review). 0x-prefixed 32-byte hex nonce
|
|
6408
|
-
* issued in the most-recent `requestPayment` yield; the SDK rejects mid-job
|
|
6409
|
-
* x402 payments whose decoded `authorization.nonce` differs from this value.
|
|
6410
|
-
*/
|
|
6411
|
-
pendingX402Nonce?: string;
|
|
6412
|
-
/**
|
|
6413
|
-
* Exact USDC microunit amount advertised with `pendingX402Nonce`. Verification
|
|
6414
|
-
* reuses this value so an FX refresh between request and payment cannot change
|
|
6415
|
-
* the facilitator requirements.
|
|
6416
|
-
*/
|
|
6417
|
-
pendingX402AmountUsdcMicro?: string;
|
|
6418
|
-
/**
|
|
6419
|
-
* The outstanding `requestPayment` ask denominated in fiat micro-units, pinned
|
|
6420
|
-
* when the payment-request was emitted (internal-review) — the mid-job analogue of
|
|
6421
|
-
* `resolvePriceFiat` pinning the quote. The ledger is fiat-denominated, so the
|
|
6422
|
-
* top-up's `fund` + `growDraw` need a figure that doesn't move with the BTC/USD
|
|
6423
|
-
* rate between the ask and the payment. Absent when the ask couldn't be priced
|
|
6424
|
-
* in fiat (cold-start fx outage), which degrades that top-up to ledger-less.
|
|
6425
|
-
*/
|
|
6426
|
-
pendingPaymentFiatMicro?: number;
|
|
6427
|
-
/** Currency of {@link pendingPaymentFiatMicro} (lowercase ISO-4217). */
|
|
6428
|
-
pendingPaymentFiatCurrency?: string;
|
|
6429
|
-
/**
|
|
6430
|
-
* What this job has **cumulatively** asked for mid-job, in fiat micro-units
|
|
6431
|
-
* of {@link askedTopUpCurrency} (internal-review) — the ceiling `growDraw` caps the
|
|
6432
|
-
* job's draw growth at. Monotonic: written by the same Tx A that emits each
|
|
6433
|
-
* payment-request, and never decremented, which is exactly what
|
|
6434
|
-
* `pendingPaymentFiatMicro` is not (Tx C drains it as payments land). A cap
|
|
6435
|
-
* derived from the outstanding figure would let a duplicate payment arriving
|
|
6436
|
-
* in the window before Tx C see a full ask that the winner had already
|
|
6437
|
-
* bought.
|
|
6438
|
-
*
|
|
6439
|
-
* `-1` is a sticky "not expressible" sentinel — after internal-review the one door
|
|
6440
|
-
* left to it is an ask the rate provider was down for. Undefined means no
|
|
6441
|
-
* mid-job ask has been recorded (including a row written before this
|
|
6442
|
-
* existed). Either way the cap is skipped and growth is unbounded, as it was
|
|
6443
|
-
* before: a guessed ceiling on a money path is worse than none.
|
|
6444
|
-
*/
|
|
6445
|
-
askedTopUpMicro?: number;
|
|
6446
|
-
/**
|
|
6447
|
-
* Currency of {@link askedTopUpMicro} (lowercase ISO-4217) — and, from
|
|
6448
|
-
* internal-review, the job's own ask denomination: first-write-wins, and read back
|
|
6449
|
-
* by `ctx.requestPayment` so every later ask pins in it too. That is what
|
|
6450
|
-
* makes a mid-job currency switch unexpressible rather than merely unlikely.
|
|
6451
|
-
*/
|
|
6452
|
-
askedTopUpCurrency?: string;
|
|
6453
|
-
/**
|
|
6454
|
-
* Why this job's draw growth is **not** capped, when it isn't (internal-review) —
|
|
6455
|
-
* the durable half of the `-1` sentinel, so an operator can list the affected
|
|
6456
|
-
* jobs after the fact rather than reconstruct them from log lines. Sticky
|
|
6457
|
-
* first-writer-wins, like the sentinel itself. Null on every job whose ceiling
|
|
6458
|
-
* is enforceable, which is the overwhelming majority.
|
|
6459
|
-
*/
|
|
6460
|
-
topUpCapUnenforcedReason?: TopUpCapUnenforcedReason;
|
|
6461
|
-
/** Price the job was charged at (msats). Used to detect overpayment for change/melt gating. */
|
|
6462
|
-
requiredMsats?: number;
|
|
6463
|
-
/**
|
|
6464
|
-
* The DVM-signed proof of this job's outcome (internal-review). Written once at the
|
|
6465
|
-
* terminal transition via `saveReceipt` and never rewritten — `save` leaves
|
|
6466
|
-
* the column alone so a stale in-memory snapshot can't clear it. Absent on
|
|
6467
|
-
* non-terminal jobs, and on every job when the DVM has no receipt key wired.
|
|
6468
|
-
*/
|
|
6469
|
-
receipt?: JobReceipt;
|
|
6470
|
-
stepCache: StepRecord[];
|
|
6471
|
-
state: unknown;
|
|
6472
|
-
createdAt: number;
|
|
6473
|
-
lastActivityAt: number;
|
|
6474
|
-
}
|
|
6475
|
-
/**
|
|
6476
|
-
* Counter snapshot used by the NOTIFY-driven resolver and the
|
|
6477
|
-
* `verifyAndCredit` flow (internal-review). Carries just the handler-visible state
|
|
6478
|
-
* needed to decide whether a pending payment yield can resolve, plus (internal-review)
|
|
6479
|
-
* the terminal reason so a machine adopting another machine's cancel can hand
|
|
6480
|
-
* the caller's own words to `ctx.signal.reason` and the `onCancel` hook.
|
|
6481
|
-
*/
|
|
6482
|
-
interface JobCounters {
|
|
6483
|
-
status: JobStatus;
|
|
6484
|
-
paidMsats: number;
|
|
6485
|
-
pendingPaymentMsats?: number;
|
|
6486
|
-
/**
|
|
6487
|
-
* `jobs.summary`. Set to the cancel/fail reason by `cancelJob` /
|
|
6488
|
-
* `cancelStaleJob`, and to the completion summary by a handler's
|
|
6489
|
-
* `ctx.complete(summary)`. Undefined when nothing recorded one.
|
|
6490
|
-
*/
|
|
6491
|
-
summary?: string;
|
|
6492
|
-
}
|
|
6493
|
-
/**
|
|
6494
|
-
* Credit delta written inside the Tx C transaction (internal-review) when an
|
|
6495
|
-
* inbound payment verifies. Fields mirror what the rails produce in
|
|
6496
|
-
* `payment.ts`; `paidMsatsDelta` is the only required key.
|
|
6497
|
-
*/
|
|
6498
|
-
interface PaymentCreditDelta {
|
|
6499
|
-
paidMsatsDelta: number;
|
|
6500
|
-
/** When true, set `pending_payment_msats = NULL`; otherwise decrement by the delta. */
|
|
6501
|
-
clearPending?: boolean;
|
|
6502
|
-
paymentMint?: string;
|
|
6503
|
-
paymentRail?: FundingMethod;
|
|
6504
|
-
paymentTxHash?: string;
|
|
6505
|
-
nativeAmount?: number;
|
|
6506
|
-
nativeAsset?: "sats" | "usdc" | "usdc.e" | "usd-cents";
|
|
6507
|
-
cashuFlow?: "p2pk_accumulator";
|
|
6508
|
-
/** When true, accumulate `nativeAmount` onto the existing same-rail value; otherwise overwrite. */
|
|
6509
|
-
accumulateNative?: boolean;
|
|
6510
|
-
/** Clear the pending nonce + advertised amount after an x402 credit succeeds. */
|
|
6511
|
-
clearPendingX402Binding?: boolean;
|
|
6512
|
-
/**
|
|
6513
|
-
* Credit this payment funded (internal-review). Only ever set when the mid-job
|
|
6514
|
-
* top-up minted a *fresh* implicit credit — a free-then-paid job whose
|
|
6515
|
-
* upfront leg placed no draw. Written set-if-null: a job already bound to a
|
|
6516
|
-
* credit keeps that binding, because the top-up grew its existing draw
|
|
6517
|
-
* rather than opening a second one.
|
|
6518
|
-
*/
|
|
6519
|
-
creditId?: string;
|
|
6520
|
-
/** The draw opened alongside {@link creditId}. Same set-if-null rule. */
|
|
6521
|
-
drawId?: string;
|
|
6522
|
-
}
|
|
6523
|
-
/** Atomic side effects applied with an outgoing provider message. */
|
|
6524
|
-
interface AppendOutgoingOptions {
|
|
6525
|
-
pendingPaymentDelta?: number;
|
|
6526
|
-
pendingMppChallengeIds?: string[];
|
|
6527
|
-
pendingX402Nonce?: string;
|
|
6528
|
-
pendingX402AmountUsdcMicro?: string;
|
|
6529
|
-
/**
|
|
6530
|
-
* Fiat envelope pinned for this ask (internal-review). Accumulates alongside
|
|
6531
|
-
* `pendingPaymentDelta` when the currency matches what's already recorded,
|
|
6532
|
-
* and replaces it when it doesn't — the same shape `pending_payment_msats`
|
|
6533
|
-
* uses, so stacked asks stay summable.
|
|
6534
|
-
*/
|
|
6535
|
-
pendingPaymentFiatMicro?: number;
|
|
6536
|
-
pendingPaymentFiatCurrency?: string;
|
|
6537
|
-
}
|
|
6538
|
-
/**
|
|
6539
|
-
* Why a job's cumulative ask total can't bound its draw growth (internal-review).
|
|
6540
|
-
*
|
|
6541
|
-
* - `ask_unpriceable` — an ask the rate provider was down for, or one whose
|
|
6542
|
-
* fiat figure isn't a safe integer. The only door left after internal-review, and
|
|
6543
|
-
* deliberately still open: failing the charge to protect a ledger comparison
|
|
6544
|
-
* would break a payment that doesn't need the rate to be quoted or collected.
|
|
6545
|
-
* - `ask_currency_switch` — two asks on one job in different denominations.
|
|
6546
|
-
* Unreachable through `ctx.requestPayment`, which pins every ask in the job's
|
|
6547
|
-
* own sticky denomination; kept as the backstop for a record written by an
|
|
6548
|
-
* older build, and because the accumulator must not silently sum two units.
|
|
6549
|
-
*/
|
|
6550
|
-
type TopUpCapUnenforcedReason = "ask_unpriceable" | "ask_currency_switch";
|
|
6551
|
-
/**
|
|
6552
|
-
* Result of a Tx C `verifyAndCredit` call. `alreadyVerified` is set when the
|
|
6553
|
-
* inbound row was previously marked verified (idempotency guard); the credit
|
|
6554
|
-
* is skipped in that case.
|
|
6555
|
-
*/
|
|
6556
|
-
interface VerifyAndCreditResult {
|
|
6557
|
-
counters: JobCounters;
|
|
6558
|
-
alreadyVerified: boolean;
|
|
6559
|
-
/**
|
|
6560
|
-
* The credit the job row holds **after** this call — the authoritative
|
|
6561
|
-
* answer, read back rather than assumed (internal-review).
|
|
6562
|
-
*
|
|
6563
|
-
* {@link PaymentCreditDelta.creditId} is written set-if-null, so a caller
|
|
6564
|
-
* that passes one cannot know whether it won the bind: on a free-then-paid
|
|
6565
|
-
* job two concurrent top-ups each mint their own implicit credit and only
|
|
6566
|
-
* one lands. Reading it back is what lets `processPayment` mirror the row
|
|
6567
|
-
* truthfully and name the loser's deposit to the caller instead of silently
|
|
6568
|
-
* recording a binding the row rejected.
|
|
6569
|
-
*/
|
|
6570
|
-
creditId?: string;
|
|
6571
|
-
/** The draw the job row holds after this call. Same read-back rule. */
|
|
6572
|
-
drawId?: string;
|
|
6573
|
-
}
|
|
6574
|
-
/** Secret-free identity for atomically reserving one public request id. */
|
|
6575
|
-
interface RequestIdClaim {
|
|
6576
|
-
/** Caller-generated id carried inside the signed request body. */
|
|
6577
|
-
requestId: string;
|
|
6578
|
-
/** Verified x-only secp256k1 caller public key. */
|
|
6579
|
-
requesterPubkey: string;
|
|
6580
|
-
/** Server-resolved requester identity used by normal job ownership checks. */
|
|
6581
|
-
requesterId: string;
|
|
6582
|
-
/** Fingerprint of the request body with only the expiring auth fields removed. */
|
|
6583
|
-
requestFingerprint: string;
|
|
6584
|
-
/** Job id allocated before payment and reused by every exact recovery attempt. */
|
|
6585
|
-
jobId: string;
|
|
6586
|
-
/** Server-generated owner token for the live serialization lock. */
|
|
6587
|
-
claimToken: string;
|
|
6588
|
-
}
|
|
6589
|
-
/** Result of acquiring the live lock for a durable public request-id binding. */
|
|
6590
|
-
interface RequestIdClaimResult {
|
|
6591
|
-
/** Stable job id first assigned to this caller/request id. */
|
|
6592
|
-
jobId: string;
|
|
6593
|
-
/** True when the durable identity binding existed before this lock acquisition. */
|
|
6594
|
-
replayed: boolean;
|
|
6595
|
-
}
|
|
6596
|
-
/** Persistent backing store for job records. */
|
|
6597
|
-
interface JobStore {
|
|
6598
|
-
/** Retrieve a job record by ID. Returns undefined if not found. */
|
|
6599
|
-
get(id: string): Promise<JobRecord | undefined>;
|
|
6600
|
-
/**
|
|
6601
|
-
* Retrieve the job a settlement reference paid for (internal-review). On the cashu
|
|
6602
|
-
* accumulator path `paymentTxHash` is the caller's `X-Cashu-Request-Id`, so
|
|
6603
|
-
* this is what makes a retried paid submit idempotent: the replay finds the
|
|
6604
|
-
* job its (already-spent) payment created instead of a bare 409.
|
|
6605
|
-
*/
|
|
6606
|
-
findJobByPaymentTxHash(txHash: string): Promise<JobRecord | undefined>;
|
|
6607
|
-
/** Read a signed caller's job by public recovery id, when the store supports it. */
|
|
6608
|
-
findJobByRequestId?(requestId: string, requesterPubkey: string): Promise<JobRecord | undefined>;
|
|
6609
|
-
/**
|
|
6610
|
-
* Atomically bind and lock a caller/request id before pricing, payment
|
|
6611
|
-
* verification, credit draw, or handler work. Returns undefined when
|
|
6612
|
-
* another live request holds it or its durable binding has different
|
|
6613
|
-
* provenance. A process death releases the live lock but not the binding.
|
|
6614
|
-
*/
|
|
6615
|
-
claimRequestId?(claim: RequestIdClaim): Promise<RequestIdClaimResult | undefined>;
|
|
6616
|
-
/**
|
|
6617
|
-
* Lock an existing exact caller/request binding without creating one.
|
|
6618
|
-
* Used only by the explicit recovery route, which must prove the original
|
|
6619
|
-
* submit reached the server before it can inspect durable acceptance state.
|
|
6620
|
-
*/
|
|
6621
|
-
resumeRequestId?(claim: RequestIdClaim): Promise<RequestIdClaimResult | undefined>;
|
|
6622
|
-
/**
|
|
6623
|
-
* Release the live serialization lock after this route finishes. The opaque
|
|
6624
|
-
* owner token prevents a delayed request from releasing a newer holder; the
|
|
6625
|
-
* durable caller/fingerprint/job binding remains retained.
|
|
6626
|
-
*/
|
|
6627
|
-
releaseRequestIdClaim?(claim: RequestIdClaim): Promise<void>;
|
|
6628
|
-
/** Upsert a job record. */
|
|
6629
|
-
save(record: JobRecord): Promise<void>;
|
|
6630
|
-
/** Delete a job record. */
|
|
6631
|
-
delete(id: string): Promise<void>;
|
|
6632
|
-
}
|
|
6633
|
-
/**
|
|
6634
|
-
* JobStore extension for signed job receipts (internal-review). Implemented by both
|
|
6635
|
-
* container-tier stores (`MemoryJobStore`, `PostgresJobStore`); the isolate
|
|
6636
|
-
* tier's `IsolateJobStore` deliberately doesn't, which is what keeps the
|
|
6637
|
-
* out-of-scope isolate gap a compile-time fact rather than a runtime surprise.
|
|
6638
|
-
*/
|
|
6639
|
-
interface ReceiptIssuingStore {
|
|
6640
|
-
/**
|
|
6641
|
-
* Allocate this job's receipt sequence number, or return the one it already
|
|
6642
|
-
* holds. Idempotent per job and monotonic per DVM: two machines racing to
|
|
6643
|
-
* issue the same job's receipt get the same number, and the loser burns no
|
|
6644
|
-
* sequence.
|
|
6645
|
-
*
|
|
6646
|
-
* Gaps in the issued sequence are the completeness signal that exposes
|
|
6647
|
-
* receipt suppression, so a read-then-write counter (which can hand two jobs
|
|
6648
|
-
* the same number under concurrency) is not acceptable — the allocation has
|
|
6649
|
-
* to be atomic against every other machine.
|
|
6650
|
-
*/
|
|
6651
|
-
claimReceiptSeq(jobId: string): Promise<number>;
|
|
6652
|
-
/**
|
|
6653
|
-
* Persist a signed receipt iff the job doesn't already have one, returning
|
|
6654
|
-
* whichever receipt is stored afterwards. Write-once: a racing second issuer
|
|
6655
|
-
* gets the winner's bytes back, so every reader of the job — sync response,
|
|
6656
|
-
* poll, later re-read — sees byte-identical JSON.
|
|
6657
|
-
*
|
|
6658
|
-
* Returns `undefined` when the job row is gone.
|
|
6659
|
-
*/
|
|
6660
|
-
saveReceipt(jobId: string, receipt: JobReceipt): Promise<JobReceipt | undefined>;
|
|
6661
|
-
}
|
|
6662
|
-
/**
|
|
6663
|
-
* JobStore extension for cross-machine message streaming + the internal-review
|
|
6664
|
-
* transactional model (Tx A / Tx B / Tx C).
|
|
6665
|
-
*
|
|
6666
|
-
* Tx A — outgoing message + immediate counter consequence (`appendOutgoing`).
|
|
6667
|
-
* Single tx: server-allocate seq, append `job_messages` row with
|
|
6668
|
-
* `status='verified'`, bump `pending_payment_msats` for payment-request
|
|
6669
|
-
* messages, and `pg_notify`.
|
|
6670
|
-
*
|
|
6671
|
-
* Tx B — incoming message marked `pending-verification` (`recordInbound`).
|
|
6672
|
-
* Single tx: server-allocate seq, append `job_messages` row with
|
|
6673
|
-
* `status='pending-verification'`, and `pg_notify`. External verification
|
|
6674
|
-
* (Cashu mint, x402 facilitator, MPP server) runs OUTSIDE the tx.
|
|
6675
|
-
*
|
|
6676
|
-
* Tx C — verification outcome + credit (`verifyAndCredit`). Single tx:
|
|
6677
|
-
* flip the `job_messages.status` to `'verified'`, bump `paid_msats` /
|
|
6678
|
-
* clear `pending_payment_msats` per the credit delta, and `pg_notify`.
|
|
6679
|
-
* Idempotent — a repeat call returns `alreadyVerified: true` without
|
|
6680
|
-
* re-crediting.
|
|
6681
|
-
*/
|
|
6682
|
-
interface StreamableJobStore extends JobStore {
|
|
6683
|
-
/**
|
|
6684
|
-
* Tx A — append an outgoing message and apply its immediate counter
|
|
6685
|
-
* consequence. Returns the server-allocated seq. The caller's `message`
|
|
6686
|
-
* carries no `seq` (it's allocated inside the tx). For payment-request
|
|
6687
|
-
* messages, pass the amount via `pendingPaymentDelta` so the bump and
|
|
6688
|
-
* the message land in the same tx.
|
|
6689
|
-
*/
|
|
6690
|
-
appendOutgoing(jobId: string, message: OutgoingMessage, opts?: AppendOutgoingOptions): Promise<number>;
|
|
6691
|
-
/**
|
|
6692
|
-
* Tx B — record an inbound message durably with `pending-verification`
|
|
6693
|
-
* status. Returns the server-allocated seq.
|
|
6694
|
-
*/
|
|
6695
|
-
recordInbound(jobId: string, message: OutgoingMessage): Promise<number>;
|
|
6696
|
-
/**
|
|
6697
|
-
* Tx C — flip an inbound message from `pending-verification` to either
|
|
6698
|
-
* `verified` (with a credit delta when it's a payment) or `failed-verify`
|
|
6699
|
-
* (when verification rejected). Idempotent: a repeat call with a row
|
|
6700
|
-
* already in `verified`/`failed-verify` returns `alreadyVerified: true`
|
|
6701
|
-
* and skips the credit.
|
|
6702
|
-
*
|
|
6703
|
-
* Pass `credit: null` for non-payment messages (response/cancel/approval).
|
|
6704
|
-
*/
|
|
6705
|
-
verifyAndCredit(jobId: string, seq: number, credit: PaymentCreditDelta | null): Promise<VerifyAndCreditResult>;
|
|
6706
|
-
/**
|
|
6707
|
-
* Read back what Tx C committed for an inbound message, without opening a
|
|
6708
|
-
* transaction of its own (internal-review).
|
|
6709
|
-
*
|
|
6710
|
-
* A `verifyAndCredit` that throws is ambiguous: the error may have been
|
|
6711
|
-
* raised at or after its COMMIT, in which case the write is durable and the
|
|
6712
|
-
* caller has simply lost the acknowledgement. Retrying resolves that — until
|
|
6713
|
-
* the retries run out, and the last attempt's error is as ambiguous as any
|
|
6714
|
-
* other's. This is the read that settles it: `undefined` means Tx C has not
|
|
6715
|
-
* committed for this seq, anything else is the outcome it committed.
|
|
6716
|
-
*
|
|
6717
|
-
* Implementations MUST answer without a transaction (no `BEGIN`/`COMMIT`) and
|
|
6718
|
-
* MUST NOT write, because the caller reaches for it precisely when writes are
|
|
6719
|
-
* failing. `alreadyVerified` is always `true` on the returned value — the
|
|
6720
|
-
* credit landed in an earlier call, not this one.
|
|
6721
|
-
*/
|
|
6722
|
-
getVerifiedInbound(jobId: string, seq: number): Promise<VerifyAndCreditResult | undefined>;
|
|
6723
|
-
/**
|
|
6724
|
-
* Mark an inbound message as failed-verify without crediting. Used when
|
|
6725
|
-
* external verification rejects the payment (Cashu mint says SPENT, x402
|
|
6726
|
-
* facilitator returns invalid, mppx HMAC mismatch).
|
|
6727
|
-
*/
|
|
6728
|
-
markInboundFailed(jobId: string, seq: number, reason: string): Promise<void>;
|
|
6729
|
-
/** Read the counters used by the resolver (status / paid / pending). */
|
|
6730
|
-
getCounters(jobId: string): Promise<JobCounters | undefined>;
|
|
6731
|
-
/**
|
|
6732
|
-
* Single-execution claim (internal-review). Atomically flip a job from
|
|
6733
|
-
* `awaiting-input` to `processing`, returning `true` only for the caller
|
|
6734
|
-
* that won the transition. After a mid-job payment lands cross-machine, the
|
|
6735
|
-
* live original handler (woken via NOTIFY) and a reactivation replay on the
|
|
6736
|
-
* paying machine both race to drive the job; the CAS winner proceeds and the
|
|
6737
|
-
* loser stands down, so a healthy worker never double-executes (double
|
|
6738
|
-
* substrate spend, clobbered artifact). Also bumps `last_activity_at` so the
|
|
6739
|
-
* claimant is covered by the processing watchdog. A no-op returning `false`
|
|
6740
|
-
* for a job that is no longer `awaiting-input` (already claimed / terminal).
|
|
6741
|
-
*/
|
|
6742
|
-
claimForProcessing(jobId: string): Promise<boolean>;
|
|
6743
|
-
/**
|
|
6744
|
-
* Run `fn` while holding a tx-scoped advisory lock keyed on the job id.
|
|
6745
|
-
* Resolves with `{ acquired: false }` when the lock is already held by
|
|
6746
|
-
* another transaction — the caller decides what to do (typically: skip
|
|
6747
|
-
* reactivation, the other holder will handle it). The lock releases on
|
|
6748
|
-
* commit/rollback of the wrapping tx.
|
|
6749
|
-
*/
|
|
6750
|
-
tryReactivationLock<T>(jobId: string, fn: () => Promise<T>): Promise<{
|
|
6751
|
-
acquired: true;
|
|
6752
|
-
result: T;
|
|
6753
|
-
} | {
|
|
6754
|
-
acquired: false;
|
|
6755
|
-
}>;
|
|
6756
|
-
/**
|
|
6757
|
-
* Subscribe to messages for a job. Delivers existing messages (seq > afterSeq)
|
|
6758
|
-
* from the `job_messages` table first, then forwards new ones via NOTIFY.
|
|
6759
|
-
* Returns an unsubscribe function.
|
|
6760
|
-
*
|
|
6761
|
-
* Only messages with `status='verified'` are delivered — pending and
|
|
6762
|
-
* failed-verify rows are internal to the verification flow.
|
|
6763
|
-
*/
|
|
6764
|
-
subscribeMessages(jobId: string, afterSeq: number, onMessage: (msg: Message) => void): Promise<() => void>;
|
|
6765
|
-
/**
|
|
6766
|
-
* Subscribe to raw NOTIFY events for a job. Fires once per `pg_notify`
|
|
6767
|
-
* delivery; no message decoding. Used by `Context.requestPayment` to
|
|
6768
|
-
* re-read counters when cross-machine credit lands (internal-review).
|
|
6769
|
-
*/
|
|
6770
|
-
subscribeNotifications(jobId: string, onNotify: () => void): Promise<() => void>;
|
|
6771
|
-
/** Read messages from the `job_messages` table for a job. */
|
|
6772
|
-
getMessages(jobId: string, afterSeq: number): Promise<Message[]>;
|
|
6773
|
-
/**
|
|
6774
|
-
* Find stale non-terminal jobs (internal-review / internal-review). Two status-aware
|
|
6775
|
-
* cutoffs (both Unix ms): `processing`/`working` rows older than
|
|
6776
|
-
* `processingThresholdMs` (worker-liveness watchdog — the SDK heartbeats
|
|
6777
|
-
* live workers, so a frozen `last_activity_at` here means the worker died),
|
|
6778
|
-
* and `awaiting-input` rows older than `awaitingThresholdMs` (the
|
|
6779
|
-
* caller-input idle timeout). Pass a negative cutoff to disable that arm.
|
|
6780
|
-
* Returns at most `limit` records, oldest first. Consumed exclusively by the
|
|
6781
|
-
* `JobManager` stale-job sweeper; not safe to feed into handler dispatch.
|
|
6782
|
-
*
|
|
6783
|
-
* `capabilities` scopes the query to jobs the calling JobManager owns —
|
|
6784
|
-
* multi-mount hosts where two descriptors share a DB must not steal
|
|
6785
|
-
* each other's stuck rows (the activeJobs teardown only fires on the
|
|
6786
|
-
* descriptor that actually hosted the zombie). Pass `null` only from
|
|
6787
|
-
* single-descriptor deployments.
|
|
6788
|
-
*/
|
|
6789
|
-
findStaleJobs(processingThresholdMs: number, awaitingThresholdMs: number, limit: number, capabilities: string[] | null): Promise<JobRecord[]>;
|
|
6790
|
-
/**
|
|
6791
|
-
* Atomically transition a stale job to `terminalStatus` (`failed` for a
|
|
6792
|
-
* dead worker, `cancelled` for an idle caller-wait) and append a final
|
|
6793
|
-
* `cancel` message in the same transaction (internal-review / internal-review). The
|
|
6794
|
-
* `expectedActivityBefore` clause is an optimistic CAS — the flip only
|
|
6795
|
-
* lands when the job is still non-terminal AND `last_activity_at <=
|
|
6796
|
-
* expectedActivityBefore`. Returns true when this caller claimed the
|
|
6797
|
-
* transition, false when another machine got there first OR the job's
|
|
6798
|
-
* activity bumped (recovered). Mirrors `save`'s terminal cleanup by
|
|
6799
|
-
* deleting incremental `job_messages` rows once the snapshot is final.
|
|
6800
|
-
*/
|
|
6801
|
-
cancelStaleJob(jobId: string, expectedActivityBefore: number, reason: string, terminalStatus: "failed" | "cancelled"): Promise<boolean>;
|
|
6802
|
-
/**
|
|
6803
|
-
* Atomically cancel a job from a machine that isn't running its handler
|
|
6804
|
-
* (internal-review). Same transaction shape as {@link cancelStaleJob} minus the
|
|
6805
|
-
* activity cutoff — the CAS guards only on the job still being non-terminal,
|
|
6806
|
-
* so this replaces the read-then-`save` the DELETE route used to do (a TOCTOU
|
|
6807
|
-
* against a concurrent terminal write).
|
|
6808
|
-
*
|
|
6809
|
-
* The `cancel` message and the terminal status commit together and `pg_notify`
|
|
6810
|
-
* fires inside the tx, so the machine actually running the handler wakes on
|
|
6811
|
-
* its per-job notification subscription, adopts the terminal status, and
|
|
6812
|
-
* aborts `ctx.signal` within a NOTIFY round-trip instead of at the handler's
|
|
6813
|
-
* next store write. Returns false when the job was already terminal (another
|
|
6814
|
-
* machine won).
|
|
6815
|
-
*/
|
|
6816
|
-
cancelJob(jobId: string, reason: string): Promise<boolean>;
|
|
6817
|
-
/**
|
|
6818
|
-
* Bump `last_activity_at` to `now` (Unix ms) for the given jobs that are
|
|
6819
|
-
* still in `processing`/`working` (internal-review worker heartbeat). Called on a
|
|
6820
|
-
* tick by the `JobManager` for its locally-active jobs so a live worker's
|
|
6821
|
-
* row stays fresh and the processing watchdog only fires when the process
|
|
6822
|
-
* has actually died. A no-op for rows that have since gone terminal or
|
|
6823
|
-
* `awaiting-input` (the SQL `WHERE` guards the status).
|
|
6824
|
-
*/
|
|
6825
|
-
heartbeatActiveJobs(jobIds: string[], now: number): Promise<void>;
|
|
6826
|
-
/** Acquire the dedicated LISTEN connection. Call once at startup. */
|
|
6827
|
-
initStreaming(): Promise<void>;
|
|
6828
|
-
/** Release the dedicated LISTEN connection. Call on shutdown. */
|
|
6829
|
-
shutdownStreaming(): Promise<void>;
|
|
6830
|
-
}
|
|
6831
|
-
/**
|
|
6832
|
-
* Message shape passed to `appendOutgoing` / `recordInbound`. The store
|
|
6833
|
-
* allocates `seq` server-side inside the tx, so the caller doesn't supply it.
|
|
6834
|
-
*/
|
|
6835
|
-
interface OutgoingMessage {
|
|
6836
|
-
from: "provider" | "requester";
|
|
6837
|
-
type: MessageType;
|
|
6838
|
-
timestamp: number;
|
|
6839
|
-
content: Record<string, unknown> | object;
|
|
6840
|
-
}
|
|
6841
|
-
/**
|
|
6842
|
-
* Runtime type guard for StreamableJobStore. Duck-typed, so it has to name every
|
|
6843
|
-
* member the callers reach for — a store written against an earlier version of
|
|
6844
|
-
* the interface would otherwise pass the guard and TypeError inside the route
|
|
6845
|
-
* that calls the member it's missing.
|
|
6846
|
-
*/
|
|
6847
|
-
declare function isStreamableJobStore(store: JobStore): store is StreamableJobStore;
|
|
6848
|
-
/**
|
|
6849
|
-
* The stale-job reaper surface (internal-review) — the two methods a sweeper needs to
|
|
6850
|
-
* find and atomically reap worker-stranded jobs. A strict subset of
|
|
6851
|
-
* `StreamableJobStore`: `MemoryJobStore` and `PostgresJobStore` satisfy it via
|
|
6852
|
-
* the full streamable interface, and the platform's `IsolateJobStore` (a plain
|
|
6853
|
-
* single-machine `JobStore`, not streamable) implements just these two so the
|
|
6854
|
-
* `IsolateJobManager` reaper can sweep the `isolate_jobs` table without taking
|
|
6855
|
-
* on the streaming/LISTEN machinery it doesn't need.
|
|
6856
|
-
*/
|
|
6857
|
-
interface StaleJobReapable {
|
|
6858
|
-
/** See {@link StreamableJobStore.findStaleJobs}. */
|
|
6859
|
-
findStaleJobs(processingThresholdMs: number, awaitingThresholdMs: number, limit: number, capabilities: string[] | null): Promise<JobRecord[]>;
|
|
6860
|
-
/** See {@link StreamableJobStore.cancelStaleJob}. */
|
|
6861
|
-
cancelStaleJob(jobId: string, expectedActivityBefore: number, reason: string, terminalStatus: "failed" | "cancelled"): Promise<boolean>;
|
|
6862
|
-
}
|
|
6863
|
-
/** Runtime type guard for StaleJobReapable. */
|
|
6864
|
-
declare function isStaleJobReapable(store: JobStore): store is JobStore & StaleJobReapable;
|
|
6865
|
-
|
|
6866
|
-
export { type PaymentRequired as $, type ApprovalContent as A, type SignedRequestDomain as B, type Currency as C, type DVMConfig as D, SignedRequestError as E, type SignedRequestFailure as F, type SignedRequestReplayStore as G, type SignedRequestSignOpts as H, type IncomingMessage as I, type JobRecord as J, type KVStore as K, type Logger as L, type SignedRequestStatementHeader as M, type SignedRequestVerifier as N, createSignedRequestVerifier as O, type PaymentContent as P, type QuoteConfig as Q, type ResolvedCreditConfig as R, type SDKJobContext as S, isZodSchema as T, UnsupportedCurrencyError as U, signedRequestStatementHeader as V, validateCurrency as W, type JsonValue as X, type FundingReceipt as Y, type ZodLike as Z, type JobReceipt as _, type DVMDescriptor as a, X402_DEFAULT_NETWORK as a$, type X402Version as a0, type MppxCredential as a1, type Message as a2, type MessageType as a3, type MppxChallenge as a4, X402_BATCH_SETTLEMENT_SCHEME as a5, X402_EXACT_SCHEME as a6, type ReceiptCredit as a7, type X402Wallet as a8, type ResourceInfo as a9, type PaymentRequestContent as aA, type PaymentRequiredV2 as aB, type PaymentRequirements as aC, type PaymentRequirementsV1 as aD, type PaymentRequirementsV2 as aE, PayoutReporter as aF, PostgresTempoSessionStore as aG, type PromptContent as aH, RAIL_REFUNDABLE as aI, type ReceiptOutcome as aJ, type ReceiptPayment as aK, RevenueReporter as aL, SIGNED_ENVELOPE_FIELDS as aM, SIGNED_ENVELOPE_TYPES as aN, type SettleResponse as aO, type StaleJobReapable as aP, StepCache as aQ, type StepRecord as aR, type TextContent as aS, type UnsignedDrainReceipt as aT, type UnsignedFundingReceipt as aU, type UnsignedJobReceipt as aV, type VerifyResponse as aW, type WorkingContent as aX, type X402ResponseBody as aY, type X402SelfRelayRpcFailureReason as aZ, type X402TrackedChannel as a_, type X402Config as aa, type X402ExactVersionSupport as ab, type X402Receipt as ac, type TransactionalPayoutHook as ad, type CashuMeltCompleted as ae, type BuildPaymentRequirementsOpts as af, type CapabilityDescriptor as ag, type CashuMode as ah, type CompleteContent as ai, type CreditDepositPayload as aj, type DrainReceipt as ak, type DrainReceiptEvent as al, type ExactEvmPayload as am, type ExactEvmPayloadAuthorization as an, type FundingLot as ao, type FundingMethod as ap, type LotDebit as aq, type LotDepletion as ar, type MessageFrom as as, type MppxServer as at, NON_CHANNEL_BITCOIN_RAILS as au, type NonChannelBitcoinRail as av, type OutgoingMessage as aw, type PaymentPayload as ax, type PaymentPayloadV1 as ay, type PaymentPayloadV2 as az, type ArtifactContent as b, type InvoiceSettlement as b$, X402_V1_VERSION as b0, X402_VERSION as b1, _testing as b2, buildPaymentRequiredV2 as b3, buildPaymentRequirements as b4, caip2ToX402Network as b5, canonicalRequestPath as b6, canonicaliseForSigning as b7, canonicalize as b8, chainIdFromCaip2 as b9, paymentRequiredV2FromV1 as bA, settleWithFacilitator as bB, signDrainReceipt as bC, signFundingReceipt as bD, signReceipt as bE, usdcContractByCaip2 as bF, usdcContractFor as bG, usdcDomainNameFor as bH, usdcDomainVersionFor as bI, verifyDrainReceipt as bJ, verifyFundingReceipt as bK, verifyReceipt as bL, verifyWithFacilitator as bM, wrapMppx as bN, x402NetworkToCaip2 as bO, type CreditDrainEnqueue as bP, type DVMAuthScheme as bQ, type CreditLedgerLike as bR, type X402RefundSettlementGate as bS, type CreditSnapshot as bT, type DrawResult as bU, type X402SettlementStatus as bV, type X402UnresolvedRefund as bW, type GrownDrawResult as bX, type DrawResolution as bY, type FundingRecord as bZ, type CreditInvoiceRecord as b_, computeResultHash as ba, createDefaultReplayStore as bb, decodePayment as bc, decodePaymentRequiredHeader as bd, depleteLots as be, encodePayment as bf, encodePaymentRequiredHeader as bg, encodeSettleResponseHeader as bh, exactEvmAuthorization as bi, fifoOrder as bj, inKindDrawMsats as bk, isArtifactMessage as bl, isCancelMessage as bm, isCompleteMessage as bn, isDrainReceipt as bo, isFundingReceipt as bp, isInKindDepletion as bq, isNonChannelBitcoinRail as br, isPaymentRequestMessage as bs, isPromptMessage as bt, isSignedJobReceipt as bu, isStaleJobReapable as bv, isTextMessage as bw, isWorkingMessage as bx, lotOwedSats as by, netOwedSats as bz, type CancelContent as c, parseProtocolVersion as c$, type BlockedInvoiceCursor as c0, type InvoiceReconciliation as c1, type InvoiceWriteOff as c2, type DrawRecord as c3, type StalePendingDrawCursor as c4, type TempoCreditLossEvidence as c5, type CreditLedgerQuerier as c6, type TempoCreditLoss as c7, type X402CreditLossEvidence as c8, type X402CreditLoss as c9, CreditLedgerError as cA, type CreditLedgerErrorCode as cB, type CreditLedgerErrorDetails as cC, type CreditLedgerPool as cD, type CreditStatus as cE, DRAIN_DELIVERY_RESERVE_SATS as cF, DVM_PROTOCOL_VERSION as cG, type DrainConflictReason as cH, type DrawRailValue as cI, type DrawStatus as cJ, PostgresX402ChannelStorage as cK, type ReplayStoreBackend as cL, type RevenueSkippedNoRailPayload as cM, type RevenueSkippedNoRailReason as cN, type Secp256k1AuthOpts as cO, type X402ChannelStorageOpts as cP, type X402RelayLockHolder as cQ, type X402RelaySubmissionLock as cR, X402RelaySubmissionLockError as cS, allocateDrawValue as cT, clientCompatibilityAttributes as cU, clientCompatibilityMiddleware as cV, clientUpgradeRequired as cW, isStreamableJobStore as cX, parseClientCapabilities as cY, parseClientCompatibility as cZ, parseDvmClient as c_, type DrainMethod as ca, type DrainRequestResult as cb, type BitcoinDepositLiability as cc, type CreditDrainRecord as cd, type ChannelDrainCursor as ce, type DrainWriteOff as cf, type DrainReleaseResult as cg, type DrainFulfilment as ch, type DrainTransitionResult as ci, type StreamableJobStore as cj, type ReceiptIssuingStore as ck, type RequestIdClaim as cl, type RequestIdClaimResult as cm, type AppendOutgoingOptions as cn, type PaymentCreditDelta as co, type VerifyAndCreditResult as cp, type JobCounters as cq, CLIENT_COMPATIBILITY_HEADERS as cr, type ClientCompatibility as cs, type ClientCompatibilityEnv as ct, type ClientCompatibilityGate as cu, type ClientCompatibilityRequirement as cv, type ClientSemVer as cw, type CreditFundingBasis as cx, type CreditInvoiceStatus as cy, CreditLedger as cz, type CanonicalEnvelope as d, requireClientCompatibility as d0, secp256k1Auth as d1, signedRequestInput as d2, type CreditDepositEnqueue as d3, type TopUpCapUnenforcedReason as d4, type X402SettlementIntent as d5, type X402SettlementCursor as d6, type X402SettlementWriteOff as d7, type X402FacilitatorAuth as d8, type X402BatchSettlementConfig as d9, type X402PayoutObserver as da, type X402SettlementReconciliationReason as db, type CreditDrawReleaseEnqueue as dc, type CreateSignedRequestVerifierOpts as e, type CreditConfig as f, type CreditView as g, DEFAULT_CREDIT_MAX as h, DEFAULT_CREDIT_MIN as i, DEFAULT_CREDIT_TTL_SECONDS as j, type DVMRouteContext as k, type InputType as l, InvalidCurrencyError as m, type JobStatus as n, type JobStore as o, type PaymentMethod as p, type PriceValue as q, type ProgressContent as r, type PromptOpts as s, type QuoteContext as t, type QuoteResult as u, type ResponseContent as v, type SDKPaymentRequestOpts as w, SIGNED_REQUEST_AUTH_ID as x, SIGNED_REQUEST_STATEMENT_VERSION as y, type SignedRequestAudience as z };
|
|
6312
|
+
export { type MppxCredential as $, type ApprovalContent as A, SignedRequestError as B, type Currency as C, type DVMConfig as D, type SignedRequestFailure as E, type SignedRequestReplayStore as F, type SignedRequestSignOpts as G, type SignedRequestStatementHeader as H, type IncomingMessage as I, type SignedRequestVerifier as J, type KVStore as K, type Logger as L, createSignedRequestVerifier as M, isZodSchema as N, signedRequestStatementHeader as O, type PaymentContent as P, type QuoteConfig as Q, type ResolvedCreditConfig as R, type SDKJobContext as S, validateCurrency as T, UnsupportedCurrencyError as U, type JsonValue as V, type FundingReceipt as W, type JobReceipt as X, type PaymentRequired as Y, type ZodLike as Z, type X402Version as _, type DVMDescriptor as a, isFundingReceipt as a$, type Message as a0, type MessageType as a1, type MppxChallenge as a2, X402_BATCH_SETTLEMENT_SCHEME as a3, X402_EXACT_SCHEME as a4, type ReceiptCredit as a5, type X402Wallet as a6, type ResourceInfo as a7, type BuildPaymentRequirementsOpts as a8, type CapabilityDescriptor as a9, type UnsignedJobReceipt as aA, type VerifyResponse as aB, type WorkingContent as aC, type X402Config as aD, type X402ResponseBody as aE, type X402SelfRelayRpcFailureReason as aF, X402_DEFAULT_NETWORK as aG, X402_V1_VERSION as aH, X402_VERSION as aI, buildPaymentRequiredV2 as aJ, buildPaymentRequirements as aK, caip2ToX402Network as aL, canonicalRequestPath as aM, canonicaliseForSigning as aN, canonicalize as aO, chainIdFromCaip2 as aP, computeResultHash as aQ, decodePayment as aR, decodePaymentRequiredHeader as aS, encodePayment as aT, encodePaymentRequiredHeader as aU, encodeSettleResponseHeader as aV, exactEvmAuthorization as aW, isArtifactMessage as aX, isCancelMessage as aY, isCompleteMessage as aZ, isDrainReceipt as a_, type CashuMode as aa, type CompleteContent as ab, type DrainReceipt as ac, type DrainReceiptEvent as ad, type ExactEvmPayload as ae, type ExactEvmPayloadAuthorization as af, type FundingMethod as ag, type MessageFrom as ah, type PaymentPayload as ai, type PaymentPayloadV1 as aj, type PaymentPayloadV2 as ak, type PaymentRequestContent as al, type PaymentRequiredV2 as am, type PaymentRequirements as an, type PaymentRequirementsV1 as ao, type PaymentRequirementsV2 as ap, type PromptContent as aq, RAIL_REFUNDABLE as ar, type ReceiptOutcome as as, type ReceiptPayment as at, type SettleResponse as au, StepCache as av, type StepRecord as aw, type TextContent as ax, type UnsignedDrainReceipt as ay, type UnsignedFundingReceipt as az, type ArtifactContent as b, type TempoCreditLossEvidence as b$, isPaymentRequestMessage as b0, isPromptMessage as b1, isSignedJobReceipt as b2, isTextMessage as b3, isWorkingMessage as b4, paymentRequiredV2FromV1 as b5, signDrainReceipt as b6, signFundingReceipt as b7, signReceipt as b8, usdcContractByCaip2 as b9, createDefaultReplayStore as bA, depleteLots as bB, fifoOrder as bC, inKindDrawMsats as bD, isInKindDepletion as bE, isNonChannelBitcoinRail as bF, lotOwedSats as bG, netOwedSats as bH, wrapMppx as bI, type CreditDrainEnqueue as bJ, type DVMAuthScheme as bK, type CreditLedgerLike as bL, type X402RefundSettlementGate as bM, type CreditSnapshot as bN, type DrawResult as bO, type X402SettlementStatus as bP, type X402UnresolvedRefund as bQ, type GrownDrawResult as bR, type DrawResolution as bS, type FundingRecord as bT, type CreditInvoiceRecord as bU, type InvoiceSettlement as bV, type BlockedInvoiceCursor as bW, type InvoiceReconciliation as bX, type InvoiceWriteOff as bY, type DrawRecord as bZ, type StalePendingDrawCursor as b_, usdcContractFor as ba, usdcDomainNameFor as bb, usdcDomainVersionFor as bc, verifyDrainReceipt as bd, verifyFundingReceipt as be, verifyReceipt as bf, x402NetworkToCaip2 as bg, type X402ExactVersionSupport as bh, type X402Receipt as bi, type TransactionalPayoutHook as bj, type CashuMeltCompleted as bk, type CreditDepositPayload as bl, type CreditDrainPayload as bm, type FundingLot as bn, type LotDebit as bo, type LotDepletion as bp, type MppxServer as bq, NON_CHANNEL_BITCOIN_RAILS as br, type NonChannelBitcoinRail as bs, PayoutReporter as bt, PostgresTempoSessionStore as bu, RevenueReporter as bv, SIGNED_ENVELOPE_FIELDS as bw, SIGNED_ENVELOPE_TYPES as bx, type X402TrackedChannel as by, _testing as bz, type CancelContent as c, type CreditLedgerQuerier as c0, type TempoCreditLoss as c1, type X402CreditLossEvidence as c2, type X402CreditLoss as c3, type DrainMethod as c4, type DrainRequestResult as c5, type BitcoinDepositLiability as c6, type CreditDrainRecord as c7, type ChannelDrainCursor as c8, type DrainWriteOff as c9, type Secp256k1AuthOpts as cA, type X402ChannelStorageOpts as cB, type X402RelayLockHolder as cC, type X402RelaySubmissionLock as cD, X402RelaySubmissionLockError as cE, allocateDrawValue as cF, clientCompatibilityAttributes as cG, clientCompatibilityMiddleware as cH, clientUpgradeRequired as cI, parseClientCapabilities as cJ, parseClientCompatibility as cK, parseDvmClient as cL, parseProtocolVersion as cM, requireClientCompatibility as cN, secp256k1Auth as cO, signedRequestInput as cP, type X402SettlementIntent as cQ, type X402SettlementCursor as cR, type X402SettlementWriteOff as cS, type X402FacilitatorAuth as cT, type X402BatchSettlementConfig as cU, type X402PayoutObserver as cV, type CreditDepositEnqueue as cW, type X402SettlementReconciliationReason as cX, type CreditDrawReleaseEnqueue as cY, type DrainReleaseResult as ca, type DrainFulfilment as cb, type DrainTransitionResult as cc, CLIENT_COMPATIBILITY_HEADERS as cd, type ClientCompatibility as ce, type ClientCompatibilityEnv as cf, type ClientCompatibilityGate as cg, type ClientCompatibilityRequirement as ch, type ClientSemVer as ci, type CreditFundingBasis as cj, type CreditInvoiceStatus as ck, CreditLedger as cl, CreditLedgerError as cm, type CreditLedgerErrorCode as cn, type CreditLedgerErrorDetails as co, type CreditLedgerPool as cp, type CreditStatus as cq, DRAIN_DELIVERY_RESERVE_SATS as cr, DVM_PROTOCOL_VERSION as cs, type DrainConflictReason as ct, type DrawRailValue as cu, type DrawStatus as cv, PostgresX402ChannelStorage as cw, type ReplayStoreBackend as cx, type RevenueSkippedNoRailPayload as cy, type RevenueSkippedNoRailReason as cz, type CanonicalEnvelope as d, type CreateSignedRequestVerifierOpts as e, type CreditConfig as f, type CreditView as g, DEFAULT_CREDIT_MAX as h, DEFAULT_CREDIT_MIN as i, DEFAULT_CREDIT_TTL_SECONDS as j, DEFAULT_JOB_RETENTION_DAYS as k, type DVMRouteContext as l, type InputType as m, InvalidCurrencyError as n, type PaymentMethod as o, type PriceValue as p, type ProgressContent as q, type PromptOpts as r, type QuoteContext as s, type QuoteResult as t, type ResponseContent as u, type SDKPaymentRequestOpts as v, SIGNED_REQUEST_AUTH_ID as w, SIGNED_REQUEST_STATEMENT_VERSION as x, type SignedRequestAudience as y, type SignedRequestDomain as z };
|