@primitivedotdev/sdk 1.4.0 → 1.6.0

package/dist/x402/index.d.ts

@@ -184,9 +184,27 @@ interface X402SpendPolicy {
   /** Allowed payee org ids; null = any on-net payee, [] = deny all. */
   allowlist: string[] | null;
 }
-interface X402ChargeInput {
-  /** Amount in token base units (USDC has 6 decimals, so "10000" = 0.01). */
+/** A payment the org's spend policy refused (read shape). */
+interface X402DeclinedPayment {
+  id: string;
+  challenge_id: string | null;
+  counterparty_org: string | null;
+  network: string;
   amount: string;
+  reason: string;
+  declined_at: string;
+}
+interface X402ChargeInput {
+  /**
+   * Amount in token base units (USDC has 6 decimals, so "10000" = 0.01).
+   * Provide exactly one of `amount` or `amountUsdc`.
+   */
+  amount?: string;
+  /**
+   * Amount as human USDC (e.g. "0.01"), converted to base units for you.
+   * Provide exactly one of `amount` or `amountUsdc`.
+   */
+  amountUsdc?: string;
   /** Defaults to "base-sepolia". */
   network?: string;
   /** The org id allowed to pay this challenge (on-net binding). */
@@ -196,6 +214,11 @@ interface X402ChargeInput {
   resource?: string;
   /** Seconds until the challenge expires (default 1h). */
   expiresIn?: number;
+  /**
+   * Optional idempotency key. Retrying `charge()` with the same key returns the
+   * original challenge instead of creating a duplicate.
+   */
+  idempotencyKey?: string;
 }
 declare class X402Error extends Error {
   /** HTTP status, or 0 for a client-side / transport error that never reached the server. */
@@ -238,16 +261,25 @@ declare class X402Client {
    * address becomes (or updates to) the default payout destination for the
    * network. `charge()` resolves its `pay_to` from this directory, so a payee
    * must register before requesting payments.
+   *
+   * `org` is optional: when omitted it is resolved from your authenticated
+   * account, so most callers never need to supply it.
    */
   registerPayoutAddress(input: {
-    org: string;
+    org?: string;
     network?: string;
     issuedAt?: string;
+    label?: string;
   }, options: {
     signer: X402Signer;
   }): Promise<X402PayoutAddress>;
   /** List your org's registered payout addresses. */
   listPayoutAddresses(): Promise<X402PayoutAddress[]>;
+  /**
+   * List the most recent payments your org's spend policy declined (newest
+   * first). Use this to see why an outbound payment was refused.
+   */
+  listDeclinedPayments(): Promise<X402DeclinedPayment[]>;
   /** Read your org's spend policy (kill-switch + caps + allowlist). */
   getSpendPolicy(): Promise<X402SpendPolicy>;
   /**
@@ -260,4 +292,4 @@ declare class X402Client {
 }
 declare function createX402Client(options?: X402ClientOptions): X402Client;
 //#endregion
-export { NonceBinding, PayoutRegistrationMessageInput, TRANSFER_WITH_AUTHORIZATION_TYPES, TokenDomain, TransferAuthorization, TransferWithAuthorizationTypedData, X402Challenge, X402ChargeInput, X402Client, X402ClientOptions, X402Error, X402PaymentPayload, X402PaymentRequirements, X402PayoutAddress, X402Receipt, X402Signer, X402SpendPolicy, buildPayoutRegistrationMessage, createX402Client, deriveEip3009Nonce, toPaymentPayload, transferWithAuthorizationTypedData };
+export { NonceBinding, PayoutRegistrationMessageInput, TRANSFER_WITH_AUTHORIZATION_TYPES, TokenDomain, TransferAuthorization, TransferWithAuthorizationTypedData, X402Challenge, X402ChargeInput, X402Client, X402ClientOptions, X402DeclinedPayment, X402Error, X402PaymentPayload, X402PaymentRequirements, X402PayoutAddress, X402Receipt, X402Signer, X402SpendPolicy, buildPayoutRegistrationMessage, createX402Client, deriveEip3009Nonce, toPaymentPayload, transferWithAuthorizationTypedData };

package/dist/x402/index.js

@@ -127,12 +127,22 @@ const SETTLEMENT_MARGIN_SEC = 300;
 const DEFAULT_BASE_URL = "https://api.primitive.dev";
 const CHARGE_INPUT_KEYS = {
 	amount: true,
+	amountUsdc: true,
 	network: true,
 	payerOrg: true,
 	description: true,
 	resource: true,
-	expiresIn: true
+	expiresIn: true,
+	idempotencyKey: true
 };
+function usdcToBaseUnits(human) {
+	const trimmed = human.trim();
+	if (!/^\d+(\.\d+)?$/.test(trimmed)) return null;
+	const [whole, frac = ""] = trimmed.split(".");
+	if (frac.length > 6) return null;
+	const base = BigInt(whole) * 1000000n + BigInt(frac.padEnd(6, "0"));
+	return base > 0n ? base.toString() : null;
+}
 var X402Error = class extends Error {
 	/** HTTP status, or 0 for a client-side / transport error that never reached the server. */
 	status;
@@ -189,7 +199,8 @@ var X402Client = class {
 				method,
 				headers: {
 					authorization: `Bearer ${this.#apiKey}`,
-					"content-type": "application/json"
+					"content-type": "application/json",
+					...init?.headers
 				},
 				body: body === void 0 ? void 0 : JSON.stringify(body),
 				signal
@@ -212,16 +223,18 @@ var X402Client = class {
 	/** Request a payment (payee side). Returns the challenge to hand to the payer. */
 	async charge(input) {
 		for (const key of Object.keys(input)) if (!(key in CHARGE_INPUT_KEYS)) throw new X402Error(`unknown charge() option "${key}"; expected one of: ${Object.keys(CHARGE_INPUT_KEYS).join(", ")}`, 0);
-		if (!input.amount || !/^[1-9][0-9]{0,38}$/.test(input.amount)) throw new X402Error("charge() requires `amount` as a positive integer string in token base units, e.g. \"10000\"", 0);
+		if (input.amount !== void 0 && input.amountUsdc !== void 0) throw new X402Error("charge() takes exactly one of `amount` (base units) or `amountUsdc` (human USDC), not both", 0);
+		const amount = input.amountUsdc !== void 0 ? usdcToBaseUnits(input.amountUsdc) : input.amount ?? null;
+		if (!amount || !/^[1-9][0-9]{0,38}$/.test(amount)) throw new X402Error("charge() requires `amount` as a positive integer string in token base units (e.g. \"10000\"), or `amountUsdc` as a positive USDC amount with at most 6 decimals (e.g. \"0.01\")", 0);
 		const body = {
-			amount: input.amount,
+			amount,
 			network: input.network ?? "base-sepolia"
 		};
 		if (input.payerOrg) body.payer_org = input.payerOrg;
 		if (input.description) body.description = input.description;
 		if (input.resource) body.resource = input.resource;
 		if (input.expiresIn !== void 0) body.expires_in = input.expiresIn;
-		return this.#request("POST", "/v1/x402/challenges", body);
+		return this.#request("POST", "/v1/x402/challenges", body, { headers: input.idempotencyKey ? { "idempotency-key": input.idempotencyKey } : void 0 });
 	}
 	/**
 	* Pay a challenge (payer side). Derives the interaction-bound authorization,
@@ -268,21 +281,30 @@ var X402Client = class {
 		if (!id) throw new X402Error("getChallenge() requires a challenge id", 0);
 		return this.#request("GET", `/v1/x402/challenges/${encodeURIComponent(id)}`);
 	}
+	/** Resolve the caller's own organization id from the account endpoint. */
+	async #resolveOrgId() {
+		const account = await this.#request("GET", "/v1/account");
+		if (!account?.id) throw new X402Error("could not resolve your organization id from /v1/account; pass { org } explicitly", 0);
+		return account.id;
+	}
 	/**
 	* Register a payout address for your org (payee side). The signer proves
 	* control of its own address with an org-bound `personal_sign`; the proven
 	* address becomes (or updates to) the default payout destination for the
 	* network. `charge()` resolves its `pay_to` from this directory, so a payee
 	* must register before requesting payments.
+	*
+	* `org` is optional: when omitted it is resolved from your authenticated
+	* account, so most callers never need to supply it.
 	*/
 	async registerPayoutAddress(input, options) {
-		if (!input?.org) throw new X402Error("registerPayoutAddress() requires an org id", 0);
 		if (typeof options?.signer?.signMessage !== "function") throw new X402Error("registerPayoutAddress() requires a signer with signMessage (e.g. a viem LocalAccount)", 0);
+		const org = input.org ?? await this.#resolveOrgId();
 		const network = input.network ?? "base-sepolia";
 		const issuedAt = input.issuedAt ?? (/* @__PURE__ */ new Date()).toISOString();
 		const address = options.signer.address;
 		const message = buildPayoutRegistrationMessage({
-			org: input.org,
+			org,
 			address,
 			network,
 			issuedAt
@@ -292,13 +314,21 @@ var X402Client = class {
 			address,
 			network,
 			signature,
-			issued_at: issuedAt
+			issued_at: issuedAt,
+			...input.label !== void 0 ? { label: input.label } : {}
 		});
 	}
 	/** List your org's registered payout addresses. */
 	async listPayoutAddresses() {
 		return this.#request("GET", "/v1/x402/payout-addresses");
 	}
+	/**
+	* List the most recent payments your org's spend policy declined (newest
+	* first). Use this to see why an outbound payment was refused.
+	*/
+	async listDeclinedPayments() {
+		return this.#request("GET", "/v1/x402/declined-payments");
+	}
 	/** Read your org's spend policy (kill-switch + caps + allowlist). */
 	async getSpendPolicy() {
 		return this.#request("GET", "/v1/x402/spend-policy");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/sdk",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "Official Primitive Node.js SDK: webhook, api, openapi, contract, and parser runtime modules.",
   "type": "module",
   "module": "./dist/index.js",