mppx 0.0.1 → 0.1.0

package/src/Receipt.test.ts

@@ -0,0 +1,98 @@
+import { Receipt } from 'mppx'
+import { describe, expect, test } from 'vitest'
+
+describe('from', () => {
+  test('behavior: creates receipt with success status', () => {
+    const receipt = Receipt.from({
+      method: 'tempo',
+      reference: '0x1234',
+      status: 'success',
+      timestamp: '2025-01-21T12:00:00.000Z',
+    })
+
+    expect(receipt).toMatchInlineSnapshot(`
+      {
+        "method": "tempo",
+        "reference": "0x1234",
+        "status": "success",
+        "timestamp": "2025-01-21T12:00:00.000Z",
+      }
+    `)
+  })
+
+  test('error: rejects receipt with failed status', () => {
+    expect(() =>
+      Receipt.from({
+        method: 'tempo',
+        reference: '0xabcd',
+        status: 'failed' as 'success',
+        timestamp: '2025-01-21T13:00:00.000Z',
+      }),
+    ).toThrow()
+  })
+})
+
+describe('serialize', () => {
+  test('behavior: serializes receipt to base64url', () => {
+    const receipt = Receipt.from({
+      method: 'tempo',
+      reference: '0x1234',
+      status: 'success',
+      timestamp: '2025-01-21T12:00:00.000Z',
+    })
+
+    const header = Receipt.serialize(receipt)
+
+    expect(header).toMatchInlineSnapshot(
+      `"eyJtZXRob2QiOiJ0ZW1wbyIsInJlZmVyZW5jZSI6IjB4MTIzNCIsInN0YXR1cyI6InN1Y2Nlc3MiLCJ0aW1lc3RhbXAiOiIyMDI1LTAxLTIxVDEyOjAwOjAwLjAwMFoifQ"`,
+    )
+  })
+})
+
+describe('deserialize', () => {
+  test('behavior: deserializes base64url to receipt', () => {
+    const encoded =
+      'eyJtZXRob2QiOiJ0ZW1wbyIsInJlZmVyZW5jZSI6IjB4MTIzNCIsInN0YXR1cyI6InN1Y2Nlc3MiLCJ0aW1lc3RhbXAiOiIyMDI1LTAxLTIxVDEyOjAwOjAwLjAwMFoifQ'
+
+    const receipt = Receipt.deserialize(encoded)
+
+    expect(receipt).toMatchInlineSnapshot(`
+      {
+        "method": "tempo",
+        "reference": "0x1234",
+        "status": "success",
+        "timestamp": "2025-01-21T12:00:00.000Z",
+      }
+    `)
+  })
+})
+
+describe('fromResponse', () => {
+  test('behavior: extracts receipt from Payment-Receipt header', () => {
+    const encoded =
+      'eyJtZXRob2QiOiJ0ZW1wbyIsInJlZmVyZW5jZSI6IjB4MTIzNCIsInN0YXR1cyI6InN1Y2Nlc3MiLCJ0aW1lc3RhbXAiOiIyMDI1LTAxLTIxVDEyOjAwOjAwLjAwMFoifQ'
+
+    const response = new Response('OK', {
+      headers: { 'Payment-Receipt': encoded },
+    })
+
+    const receipt = Receipt.fromResponse(response)
+
+    expect(receipt).toMatchInlineSnapshot(`
+      {
+        "method": "tempo",
+        "reference": "0x1234",
+        "status": "success",
+        "timestamp": "2025-01-21T12:00:00.000Z",
+      }
+    `)
+  })
+
+  test('error: throws when Payment-Receipt header is missing', () => {
+    const response = new Response('OK')
+
+    expect(() => Receipt.fromResponse(response)).toThrowErrorMatchingInlineSnapshot(
+      `[Error: Missing Payment-Receipt header.]`,
+    )
+  })
+})

package/src/Receipt.ts

@@ -0,0 +1,129 @@
+import { Base64 } from 'ox'
+import * as z from './zod.js'
+
+/**
+ * Schema for a payment receipt.
+ *
+ * @example
+ * ```ts
+ * import { Receipt } from 'mppx'
+ *
+ * const receipt = Receipt.Schema.parse(data)
+ * ```
+ */
+export const Schema = z.object({
+  /** Payment method used (e.g., "tempo", "stripe"). */
+  method: z.string(),
+  /** Method-specific reference (e.g., transaction hash). */
+  reference: z.string(),
+  /** Optional external reference ID echoed from the credential payload. */
+  externalId: z.optional(z.string()),
+  /** Payment status. Always "success" — failures use 402 + Problem Details. */
+  status: z.literal('success'),
+  /** RFC 3339 settlement timestamp. */
+  timestamp: z.datetime(),
+})
+
+/**
+ * Payment receipt returned after verification.
+ *
+ * @example
+ * ```ts
+ * import { Receipt } from 'mppx'
+ *
+ * const receipt: Receipt.Receipt = {
+ *   method: 'tempo',
+ *   status: 'success',
+ *   timestamp: new Date().toISOString(),
+ *   reference: '0x...',
+ * }
+ * ```
+ */
+export type Receipt = z.infer<typeof Schema>
+
+/**
+ * Deserializes a Payment-Receipt header value to a receipt.
+ *
+ * @param encoded - The base64url-encoded header value.
+ * @returns The deserialized receipt.
+ *
+ * @example
+ * ```ts
+ * import { Receipt } from 'mppx'
+ *
+ * const receipt = Receipt.deserialize(encoded)
+ * ```
+ */
+export function deserialize(encoded: string): Receipt {
+  const json = Base64.toString(encoded)
+  return from(JSON.parse(json))
+}
+
+/**
+ * Creates a receipt from the given parameters.
+ *
+ * @param parameters - Receipt parameters.
+ * @returns A receipt.
+ *
+ * @example
+ * ```ts
+ * import { Receipt } from 'mppx'
+ *
+ * const receipt = Receipt.from({
+ *   method: 'tempo',
+ *   status: 'success',
+ *   timestamp: new Date().toISOString(),
+ *   reference: '0x...',
+ * })
+ * ```
+ */
+export function from(parameters: from.Parameters): Receipt {
+  return Schema.parse(parameters)
+}
+
+export declare namespace from {
+  type Parameters = z.input<typeof Schema>
+}
+
+/**
+ * Serializes a receipt to the Payment-Receipt header format.
+ *
+ * @param receipt - The receipt to serialize.
+ * @returns A base64url-encoded string suitable for the Payment-Receipt header value.
+ *
+ * @example
+ * ```ts
+ * import { Receipt } from 'mppx'
+ *
+ * const header = Receipt.serialize(receipt)
+ * // => "eyJzdGF0dXMiOiJzdWNjZXNzIiwidGltZXN0YW1wIjoi..."
+ * ```
+ */
+export function serialize(receipt: Receipt): string {
+  const json = JSON.stringify(receipt)
+  return Base64.fromString(json, { pad: false, url: true })
+}
+
+/**
+ * Extracts the receipt from a Response's Payment-Receipt header.
+ *
+ * @param response - The HTTP response.
+ * @returns The deserialized receipt.
+ *
+ * @example
+ * ```ts
+ * import { Receipt } from 'mppx'
+ *
+ * const response = await fetch('/resource', {
+ *   headers: { Authorization: Credential.serialize(credential) },
+ * })
+ * if (response.ok) {
+ *   const receipt = Receipt.fromResponse(response)
+ * }
+ * ```
+ */
+export function fromResponse(response: Response): Receipt {
+  const header = response.headers.get('Payment-Receipt')
+  if (!header) throw new Error('Missing Payment-Receipt header.')
+  return deserialize(header)
+}

package/src/Store.ts

@@ -0,0 +1,84 @@
+/**
+ * Async key-value store interface.
+ *
+ * Modeled after Cloudflare KV's API (`get`/`put`/`delete`).
+ * Implementations handle serialization internally.
+ */
+import { Json } from 'ox'
+
+export type Store = {
+  get: <value = unknown>(key: string) => Promise<value | null>
+  put: (key: string, value: unknown) => Promise<void>
+  delete: (key: string) => Promise<void>
+}
+
+/** Creates a {@link Store} from an existing implementation. */
+export function from<store extends Store>(store: store): store {
+  return store
+}
+
+/** Wraps a Cloudflare KV namespace. */
+export function cloudflare(kv: cloudflare.Parameters): Store {
+  return from({
+    async get(key) {
+      const raw = await kv.get(key)
+      if (raw == null) return null as any
+      return Json.parse(raw as string)
+    },
+    async put(key, value) {
+      await kv.put(key, Json.stringify(value))
+    },
+    async delete(key) {
+      await kv.delete(key)
+    },
+  })
+}
+
+export declare namespace cloudflare {
+  export type Parameters = {
+    get: (key: string) => Promise<unknown>
+    put: (key: string, value: string) => Promise<void>
+    delete: (key: string) => Promise<void>
+  }
+}
+
+/** In-memory store backed by a `Map`. JSON-roundtrips values to match production behavior. */
+export function memory(): Store {
+  const store = new Map<string, string>()
+  return from({
+    async get(key) {
+      const raw = store.get(key)
+      if (raw === undefined) return null as any
+      return Json.parse(raw)
+    },
+    async put(key, value) {
+      store.set(key, Json.stringify(value))
+    },
+    async delete(key) {
+      store.delete(key)
+    },
+  })
+}
+
+/** Wraps an Upstash Redis instance (e.g. Vercel KV). */
+export function upstash(redis: upstash.Parameters): Store {
+  return from({
+    async get(key) {
+      return (await redis.get(key)) as any
+    },
+    async put(key, value) {
+      await redis.set(key, value)
+    },
+    async delete(key) {
+      await redis.del(key)
+    },
+  })
+}
+
+export declare namespace upstash {
+  export type Parameters = {
+    get: (key: string) => Promise<unknown>
+    set: (key: string, value: unknown) => Promise<unknown>
+    del: (key: string) => Promise<unknown>
+  }
+}