mppx 0.0.1 → 0.1.0

package/src/Errors.ts

@@ -0,0 +1,348 @@
+/**
+ * Base class for all payment-related errors.
+ */
+export abstract class PaymentError extends Error {
+  /** RFC 9457 Problem Details type URI. */
+  abstract readonly type: string
+
+  /** HTTP status code. */
+  readonly status: number = 402
+
+  /** Converts the error to RFC 9457 Problem Details format. */
+  toProblemDetails(challengeId?: string): PaymentError.ProblemDetails {
+    return {
+      type: this.type,
+      title: this.name,
+      status: this.status,
+      detail: this.message,
+      ...(challengeId && { challengeId }),
+    }
+  }
+}
+
+export declare namespace PaymentError {
+  type ProblemDetails = {
+    /** RFC 9457 Problem Details type URI. */
+    type: string
+    /** Human-readable summary. */
+    title: string
+    /** HTTP status code. */
+    status: number
+    /** Human-readable explanation. */
+    detail: string
+    /** Associated challenge ID, if applicable. */
+    challengeId?: string
+  }
+}
+
+/**
+ * Credential is malformed (invalid base64url, bad JSON structure).
+ */
+export class MalformedCredentialError extends PaymentError {
+  override readonly name = 'MalformedCredentialError'
+  readonly type = 'https://tempoxyz.github.io/payment-auth-spec/problems/malformed-credential'
+
+  constructor(options: MalformedCredentialError.Options = {}) {
+    const { reason } = options
+    super(reason ? `Credential is malformed: ${reason}.` : 'Credential is malformed.')
+  }
+}
+
+export declare namespace MalformedCredentialError {
+  type Options = {
+    /** Reason the credential is malformed (e.g., "invalid base64url", "invalid JSON"). */
+    reason?: string
+  }
+}
+
+/**
+ * Challenge ID is unknown, expired, or already used.
+ */
+export class InvalidChallengeError extends PaymentError {
+  override readonly name = 'InvalidChallengeError'
+  readonly type = 'https://tempoxyz.github.io/payment-auth-spec/problems/invalid-challenge'
+
+  constructor(options: InvalidChallengeError.Options = {}) {
+    const { id, reason } = options
+    const idPart = id ? ` "${id}"` : ''
+    const reasonPart = reason ? `: ${reason}` : ''
+    super(`Challenge${idPart} is invalid${reasonPart}.`)
+  }
+}
+
+export declare namespace InvalidChallengeError {
+  type Options = {
+    /** The invalid challenge ID. */
+    id?: string
+    /** Reason the challenge is invalid (e.g., "expired", "already used", "unknown"). */
+    reason?: string
+  }
+}
+
+/**
+ * Payment proof is invalid or verification failed.
+ */
+export class VerificationFailedError extends PaymentError {
+  override readonly name = 'VerificationFailedError'
+  readonly type = 'https://tempoxyz.github.io/payment-auth-spec/problems/verification-failed'
+
+  constructor(options: VerificationFailedError.Options = {}) {
+    const { reason } = options
+    super(reason ? `Payment verification failed: ${reason}.` : 'Payment verification failed.')
+  }
+}
+
+export declare namespace VerificationFailedError {
+  type Options = {
+    /** Reason verification failed (e.g., "invalid signature", "insufficient amount"). */
+    reason?: string
+  }
+}
+
+/**
+ * Payment requires additional action (e.g., 3DS authentication).
+ */
+export class PaymentActionRequiredError extends PaymentError {
+  override readonly name = 'PaymentActionRequiredError'
+  readonly type = 'https://tempoxyz.github.io/payment-auth-spec/problems/payment-action-required'
+
+  constructor(options: PaymentActionRequiredError.Options = {}) {
+    const { reason } = options
+    super(reason ? `Payment requires action: ${reason}.` : 'Payment requires action.')
+  }
+}
+
+export declare namespace PaymentActionRequiredError {
+  type Options = {
+    /** Reason action is required (e.g., "requires_action"). */
+    reason?: string
+  }
+}
+
+/**
+ * Payment has expired.
+ */
+export class PaymentExpiredError extends PaymentError {
+  override readonly name = 'PaymentExpiredError'
+  readonly type = 'https://tempoxyz.github.io/payment-auth-spec/problems/payment-expired'
+
+  constructor(options: PaymentExpiredError.Options = {}) {
+    const { expires } = options
+    super(expires ? `Payment expired at ${expires}.` : 'Payment has expired.')
+  }
+}
+
+export declare namespace PaymentExpiredError {
+  type Options = {
+    /** ISO 8601 expiration timestamp. */
+    expires?: string
+  }
+}
+
+/**
+ * No credential was provided but payment is required.
+ */
+export class PaymentRequiredError extends PaymentError {
+  override readonly name = 'PaymentRequiredError'
+  readonly type = 'https://tempoxyz.github.io/payment-auth-spec/problems/payment-required'
+
+  constructor(options: PaymentRequiredError.Options = {}) {
+    const { description, realm } = options
+    const parts = ['Payment is required']
+    if (realm) parts.push(`for "${realm}"`)
+    if (description) parts.push(`(${description})`)
+    super(`${parts.join(' ')}.`)
+  }
+}
+
+export declare namespace PaymentRequiredError {
+  type Options = {
+    /** Human-readable description of the payment. */
+    description?: string | undefined
+    /** Server realm (e.g., hostname). */
+    realm?: string | undefined
+  }
+}
+
+/**
+ * Credential payload does not match the expected schema.
+ */
+export class InvalidPayloadError extends PaymentError {
+  override readonly name = 'InvalidPayloadError'
+  readonly type = 'https://tempoxyz.github.io/payment-auth-spec/problems/invalid-payload'
+
+  constructor(options: InvalidPayloadError.Options = {}) {
+    const { reason } = options
+    super(reason ? `Credential payload is invalid: ${reason}.` : 'Credential payload is invalid.')
+  }
+}
+
+export declare namespace InvalidPayloadError {
+  type Options = {
+    /** Reason the payload is invalid (e.g., "missing signature field"). */
+    reason?: string
+  }
+}
+
+/**
+ * Request is malformed or contains invalid parameters.
+ */
+export class BadRequestError extends PaymentError {
+  override readonly name = 'BadRequestError'
+  override readonly status = 400
+  readonly type = 'https://tempoxyz.github.io/payment-auth-spec/problems/bad-request'
+
+  constructor(options: BadRequestError.Options = {}) {
+    const { reason } = options
+    super(reason ? `Bad request: ${reason}.` : 'Bad request.')
+  }
+}
+
+export declare namespace BadRequestError {
+  type Options = {
+    /** Reason the request is invalid. */
+    reason?: string
+  }
+}
+
+/**
+ * Insufficient balance in the payment channel.
+ */
+export class InsufficientBalanceError extends PaymentError {
+  override readonly name = 'InsufficientBalanceError'
+  override readonly status = 402
+  readonly type = 'https://paymentauth.org/problems/stream/insufficient-balance'
+
+  constructor(options: InsufficientBalanceError.Options = {}) {
+    const { reason } = options
+    super(reason ? `Insufficient balance: ${reason}.` : 'Insufficient balance.')
+  }
+}
+
+export declare namespace InsufficientBalanceError {
+  type Options = {
+    /** Reason for insufficient balance. */
+    reason?: string
+  }
+}
+
+/**
+ * Voucher or close request signature is invalid.
+ */
+export class InvalidSignatureError extends PaymentError {
+  override readonly name = 'InvalidSignatureError'
+  override readonly status = 402
+  readonly type = 'https://paymentauth.org/problems/stream/invalid-signature'
+
+  constructor(options: InvalidSignatureError.Options = {}) {
+    const { reason } = options
+    super(reason ? `Invalid signature: ${reason}.` : 'Invalid signature.')
+  }
+}
+
+export declare namespace InvalidSignatureError {
+  type Options = {
+    reason?: string
+  }
+}
+
+/**
+ * Recovered signer is not authorized for this channel.
+ */
+export class SignerMismatchError extends PaymentError {
+  override readonly name = 'SignerMismatchError'
+  override readonly status = 402
+  readonly type = 'https://paymentauth.org/problems/stream/signer-mismatch'
+
+  constructor(options: SignerMismatchError.Options = {}) {
+    const { reason } = options
+    super(reason ? `Signer mismatch: ${reason}.` : 'Signer is not authorized for this channel.')
+  }
+}
+
+export declare namespace SignerMismatchError {
+  type Options = {
+    reason?: string
+  }
+}
+
+/**
+ * Voucher cumulative amount exceeds the channel deposit.
+ */
+export class AmountExceedsDepositError extends PaymentError {
+  override readonly name = 'AmountExceedsDepositError'
+  override readonly status = 402
+  readonly type = 'https://paymentauth.org/problems/stream/amount-exceeds-deposit'
+
+  constructor(options: AmountExceedsDepositError.Options = {}) {
+    const { reason } = options
+    super(reason ? `Amount exceeds deposit: ${reason}.` : 'Voucher amount exceeds channel deposit.')
+  }
+}
+
+export declare namespace AmountExceedsDepositError {
+  type Options = {
+    reason?: string
+  }
+}
+
+/**
+ * Voucher amount increase is below the minimum delta.
+ */
+export class DeltaTooSmallError extends PaymentError {
+  override readonly name = 'DeltaTooSmallError'
+  override readonly status = 402
+  readonly type = 'https://paymentauth.org/problems/stream/delta-too-small'
+
+  constructor(options: DeltaTooSmallError.Options = {}) {
+    const { reason } = options
+    super(reason ? `Delta too small: ${reason}.` : 'Amount increase below minimum voucher delta.')
+  }
+}
+
+export declare namespace DeltaTooSmallError {
+  type Options = {
+    reason?: string
+  }
+}
+
+/**
+ * No channel with this ID exists.
+ */
+export class ChannelNotFoundError extends PaymentError {
+  override readonly name = 'ChannelNotFoundError'
+  override readonly status = 410
+  readonly type = 'https://paymentauth.org/problems/stream/channel-not-found'
+
+  constructor(options: ChannelNotFoundError.Options = {}) {
+    const { reason } = options
+    super(reason ? `Channel not found: ${reason}.` : 'No channel with this ID exists.')
+  }
+}
+
+export declare namespace ChannelNotFoundError {
+  type Options = {
+    reason?: string
+  }
+}
+
+/**
+ * Channel is closed or finalized.
+ */
+export class ChannelClosedError extends PaymentError {
+  override readonly name = 'ChannelClosedError'
+  override readonly status = 410
+  readonly type = 'https://paymentauth.org/problems/stream/channel-finalized'
+
+  constructor(options: ChannelClosedError.Options = {}) {
+    const { reason } = options
+    super(reason ? `Channel closed: ${reason}.` : 'Channel is closed.')
+  }
+}
+
+export declare namespace ChannelClosedError {
+  type Options = {
+    /** Reason the channel is closed. */
+    reason?: string
+  }
+}

package/src/Expires.ts

@@ -0,0 +1,34 @@
+/** Returns an ISO 8601 datetime string `n` days from now. */
+export function days(n: number) {
+  return new Date(Date.now() + n * 24 * 60 * 60 * 1000).toISOString()
+}
+
+/** Returns an ISO 8601 datetime string `n` hours from now. */
+export function hours(n: number) {
+  return new Date(Date.now() + n * 60 * 60 * 1000).toISOString()
+}
+
+/** Returns an ISO 8601 datetime string `n` minutes from now. */
+export function minutes(n: number) {
+  return new Date(Date.now() + n * 60 * 1000).toISOString()
+}
+
+/** Returns an ISO 8601 datetime string `n` months (30 days) from now. */
+export function months(n: number) {
+  return new Date(Date.now() + n * 30 * 24 * 60 * 60 * 1000).toISOString()
+}
+
+/** Returns an ISO 8601 datetime string `n` seconds from now. */
+export function seconds(n: number) {
+  return new Date(Date.now() + n * 1000).toISOString()
+}
+
+/** Returns an ISO 8601 datetime string `n` weeks from now. */
+export function weeks(n: number) {
+  return new Date(Date.now() + n * 7 * 24 * 60 * 60 * 1000).toISOString()
+}
+
+/** Returns an ISO 8601 datetime string `n` years (365 days) from now. */
+export function years(n: number) {
+  return new Date(Date.now() + n * 365 * 24 * 60 * 60 * 1000).toISOString()
+}

package/src/Intent.test.ts

@@ -0,0 +1,180 @@
+import { Intent } from 'mppx'
+import { describe, expect, test } from 'vitest'
+
+describe('charge', () => {
+  test('behavior: validates valid request', () => {
+    const result = Intent.charge.schema.request.parse({
+      amount: '1000',
+      currency: 'USD',
+      decimals: 6,
+    })
+    expect(result.amount).toBe('1000000000')
+    expect(result.currency).toBe('USD')
+    expect(result.expires).toMatch(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/)
+  })
+
+  test('behavior: validates with all optional fields', () => {
+    expect(
+      Intent.charge.schema.request.parse({
+        amount: '1000',
+        currency: 'USD',
+        decimals: 6,
+        description: 'Test payment',
+        expires: '2030-01-01T00:00:00Z',
+        externalId: 'order-123',
+        recipient: '0x1234567890abcdef',
+      }),
+    ).toMatchInlineSnapshot(`
+      {
+        "amount": "1000000000",
+        "currency": "USD",
+        "description": "Test payment",
+        "expires": "2030-01-01T00:00:00Z",
+        "externalId": "order-123",
+        "recipient": "0x1234567890abcdef",
+      }
+    `)
+  })
+
+  test('error: invalid amount (non-numeric)', () => {
+    expect(() =>
+      Intent.charge.schema.request.parse({
+        amount: 'abc',
+        currency: 'USD',
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(`
+      [$ZodError: [
+        {
+          "origin": "string",
+          "code": "invalid_format",
+          "format": "regex",
+          "pattern": "/^\\\\d+(\\\\.\\\\d+)?$/",
+          "path": [
+            "amount"
+          ],
+          "message": "Invalid amount"
+        },
+        {
+          "expected": "number",
+          "code": "invalid_type",
+          "path": [
+            "decimals"
+          ],
+          "message": "Invalid input"
+        }
+      ]]
+    `)
+  })
+
+  test('error: invalid amount (decimal)', () => {
+    expect(() =>
+      Intent.charge.schema.request.parse({
+        amount: '100.50',
+        currency: 'USD',
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(`
+      [$ZodError: [
+        {
+          "expected": "number",
+          "code": "invalid_type",
+          "path": [
+            "decimals"
+          ],
+          "message": "Invalid input"
+        }
+      ]]
+    `)
+  })
+
+  test('error: invalid expires (not ISO 8601)', () => {
+    expect(() =>
+      Intent.charge.schema.request.parse({
+        amount: '1000',
+        currency: 'USD',
+        expires: 'not-a-date',
+      }),
+    ).toThrowErrorMatchingInlineSnapshot(`
+      [$ZodError: [
+        {
+          "expected": "number",
+          "code": "invalid_type",
+          "path": [
+            "decimals"
+          ],
+          "message": "Invalid input"
+        },
+        {
+          "origin": "string",
+          "code": "invalid_format",
+          "format": "regex",
+          "pattern": "/^\\\\d{4}-\\\\d{2}-\\\\d{2}T\\\\d{2}:\\\\d{2}:\\\\d{2}(?:\\\\.\\\\d+)?(?:Z|[+-]\\\\d{2}:\\\\d{2})$/",
+          "path": [
+            "expires"
+          ],
+          "message": "Invalid ISO 8601 datetime"
+        }
+      ]]
+    `)
+  })
+})
+
+describe('session', () => {
+  test('behavior: converts amount to base units', () => {
+    const result = Intent.session.schema.request.parse({
+      amount: '0.000025',
+      unitType: 'llm_token',
+      currency: '0x20c0000000000000000000000000000000000001',
+      decimals: 6,
+      recipient: '0x1234567890abcdef1234567890abcdef12345678',
+    })
+    expect(result.amount).toBe('25')
+    expect(result.unitType).toBe('llm_token')
+    expect(result.currency).toBe('0x20c0000000000000000000000000000000000001')
+    expect(result).not.toHaveProperty('decimals')
+  })
+
+  test('behavior: converts suggestedDeposit to base units', () => {
+    const result = Intent.session.schema.request.parse({
+      amount: '0.000025',
+      unitType: 'llm_token',
+      currency: '0x20c0000000000000000000000000000000000001',
+      decimals: 6,
+      recipient: '0x1234567890abcdef1234567890abcdef12345678',
+      suggestedDeposit: '10',
+    })
+    expect(result.amount).toBe('25')
+    expect(result.suggestedDeposit).toBe('10000000')
+  })
+
+  test('behavior: works without suggestedDeposit', () => {
+    const result = Intent.session.schema.request.parse({
+      amount: '1',
+      unitType: 'request',
+      currency: '0x20c0000000000000000000000000000000000001',
+      decimals: 6,
+    })
+    expect(result.amount).toBe('1000000')
+    expect(result).not.toHaveProperty('suggestedDeposit')
+  })
+
+  test('error: rejects missing decimals', () => {
+    expect(() =>
+      Intent.session.schema.request.parse({
+        amount: '25',
+        unitType: 'llm_token',
+        currency: '0x20c0000000000000000000000000000000000001',
+      }),
+    ).toThrow()
+  })
+
+  test('error: rejects invalid amount', () => {
+    expect(() =>
+      Intent.session.schema.request.parse({
+        amount: 'abc',
+        unitType: 'llm_token',
+        currency: '0x20c0000000000000000000000000000000000001',
+        decimals: 6,
+      }),
+    ).toThrow()
+  })
+})

package/src/Intent.ts

@@ -0,0 +1,109 @@
+import { parseUnits } from 'viem'
+import * as Expires from './Expires.js'
+import * as z from './zod.js'
+
+/**
+ * A payment intent.
+ */
+export type Intent = {
+  name: string
+  schema: {
+    request: z.z.ZodMiniObject | z.z.ZodMiniPipe<z.z.ZodMiniObject>
+  }
+}
+
+/**
+ * Creates an intent.
+ *
+ * @example
+ * ```ts
+ * import { z } from 'mppx'
+ *
+ * const charge = Intent.from({
+ *   name: 'charge',
+ *   schema: {
+ *     request: z.object({
+ *       amount: z.string(),
+ *       currency: z.string(),
+ *       recipient: z.optional(z.string()),
+ *     }),
+ *   },
+ * })
+ * ```
+ */
+export function from<const intent extends Intent>(intent: intent): intent {
+  return intent
+}
+
+/**
+ * Charge intent for one-time immediate payments.
+ *
+ * @see https://github.com/tempoxyz/payment-auth-spec/blob/main/specs/intents/draft-payment-intent-charge-00.md
+ */
+export const charge = from({
+  name: 'charge',
+  schema: {
+    request: z.pipe(
+      z.object({
+        amount: z.amount(),
+        currency: z.string(),
+        decimals: z.number(),
+        description: z.optional(z.string()),
+        expires: z._default(z.datetime(), () => Expires.minutes(5)),
+        externalId: z.optional(z.string()),
+        recipient: z.optional(z.string()),
+      }),
+      // Note: Since the spec states we must have `amount` as a base unit, we
+      // will transform the amount to decimal units based on `decimals`.
+      z.transform(({ amount, decimals, ...rest }) => ({
+        ...rest,
+        amount: parseUnits(amount, decimals).toString(),
+      })),
+    ),
+  },
+})
+
+/**
+ * Session intent for pay-as-you-go streaming payments.
+ *
+ * Uses cumulative vouchers over a payment channel for
+ * incremental micropayments without per-request transactions.
+ */
+export const session = from({
+  name: 'session',
+  schema: {
+    request: z.pipe(
+      z.object({
+        amount: z.amount(),
+        unitType: z.string(),
+        currency: z.string(),
+        decimals: z.number(),
+        recipient: z.optional(z.string()),
+        suggestedDeposit: z.optional(z.amount()),
+      }),
+      z.transform(({ amount, decimals, suggestedDeposit, ...rest }) => ({
+        ...rest,
+        amount: parseUnits(amount, decimals).toString(),
+        ...(suggestedDeposit
+          ? { suggestedDeposit: parseUnits(suggestedDeposit, decimals).toString() }
+          : {}),
+      })),
+    ),
+  },
+})
+
+/** @internal Extracts shape from an intent's request schema, supporting both object and pipe. */
+export type ShapeOf<intent extends Intent> = intent['schema']['request'] extends z.z.ZodMiniObject
+  ? intent['schema']['request']['shape']
+  : intent['schema']['request'] extends z.z.ZodMiniPipe<infer A>
+    ? A extends z.z.ZodMiniObject
+      ? A['shape']
+      : never
+    : never
+
+/** @internal Extracts the inner object from a pipe or returns the schema directly. */
+export function shapeOf(intent: Intent): Record<string, z.z.ZodMiniType> {
+  const { request } = intent.schema
+  if ('shape' in request) return request.shape as Record<string, z.z.ZodMiniType>
+  return (request as any)._zod.def.in.shape
+}