@4mica/sdk 1.2.17 → 1.3.1

package/dist/server.d.cts

@@ -0,0 +1,119 @@
+import { o as X402PaymentRequired, v as PaymentRequirementsExtra, r as X402ResourceInfo, x as X402PaymentEnvelopeV1, y as X402PaymentEnvelopeV2 } from './models-B15ouNYG.cjs';
+export { p as PaymentRequirementsV2 } from './models-B15ouNYG.cjs';
+
+/**
+ * Edge-safe base64 helpers.
+ *
+ * Uses only Web-standard `atob`/`btoa` + `TextEncoder`/`TextDecoder`, which are
+ * available on Node (>=16), Bun, Deno, browsers, and edge/worker runtimes — so
+ * the server paywall path never depends on Node's `Buffer`.
+ */
+declare function base64ToBytes(b64: string): Uint8Array;
+declare function bytesToBase64(bytes: Uint8Array): string;
+declare function base64ToUtf8(b64: string): string;
+declare function utf8ToBase64(text: string): string;
+
+/** Decoded `X-PAYMENT` envelope: either the V1 or V2 wire shape. */
+type X402PaymentEnvelope = X402PaymentEnvelopeV1 | X402PaymentEnvelopeV2;
+/**
+ * Minimal verification surface the paywall needs: issue a payment guarantee for
+ * an already-serialized wire payload. The SDK `Client`'s `rpc` proxy and its
+ * `RpcProxy` both satisfy this structurally, so callers can pass `client.rpc`.
+ */
+interface GuaranteeVerifier {
+    issueGuarantee(payload: unknown): Promise<Record<string, unknown>>;
+}
+/** A bare verifier, or anything exposing one at `.rpc` (e.g. the SDK `Client`). */
+type PaywallVerifier = GuaranteeVerifier | {
+    rpc: GuaranteeVerifier;
+};
+/** What the framework adapter hands the paywall: method, url, and a header reader. */
+interface PaywallInput {
+    method: string;
+    url: string;
+    /** Case-insensitive header lookup, returning `null` when absent. */
+    header: (name: string) => string | null;
+}
+/** Advertised payment requirements + how to describe the protected resource. */
+interface PaywallConfig {
+    /** Recipient address that collateral is claimed against. */
+    payTo: string;
+    /** Asset (token) address, or the zero address for native ETH. */
+    asset: string;
+    /** Network id (shorthand or CAIP-2) advertised to the payer. */
+    network: string;
+    /** Amount required, as an integer string in the asset's base units. */
+    amount: string;
+    /** Endpoint the payer calls to open/resolve a tab (advertised via `extra.tabEndpoint`). */
+    tabEndpoint: string;
+    scheme?: string;
+    x402Version?: number;
+    description?: string;
+    mimeType?: string;
+    maxTimeoutSeconds?: number;
+    /** Extra requirements (e.g. a V2 validation policy); merged over `tabEndpoint`. */
+    extra?: PaymentRequirementsExtra;
+    /** Override the described resource in the 402 body. */
+    resource?: Partial<X402ResourceInfo>;
+    /** Fully override the advertised 402 body. Takes precedence over every field above. */
+    buildRequirements?: (input: PaywallInput) => X402PaymentRequired;
+}
+interface PaywallGuarantee {
+    /** ABI-encoded guarantee claims (hex). */
+    claims: string;
+    /** BLS12-381 G2 signature (hex). */
+    signature: string;
+    /** Raw guarantee record returned by the core RPC. */
+    raw: Record<string, unknown>;
+}
+type PaywallDecision = {
+    ok: true;
+    guarantee: PaywallGuarantee;
+    responseHeaders: Record<string, string>;
+} | {
+    ok: false;
+    status: 402;
+    headers: Record<string, string>;
+    body: X402PaymentRequired;
+};
+interface Paywall {
+    /** Low-level primitive: decide from a headers-in / decision-out request. */
+    protect(input: PaywallInput): Promise<PaywallDecision>;
+    /**
+     * Web-Fetch convenience wrapper. Returns a 402 `Response` when payment is
+     * required/invalid, or `{ ok: true, headers, guarantee }` for the adapter to
+     * merge onto the downstream response (the headers include `X-PAYMENT-RESPONSE`).
+     */
+    handle(request: Request): Promise<Response | {
+        ok: true;
+        headers: Headers;
+        guarantee: PaywallGuarantee;
+    }>;
+}
+
+/**
+ * Decode a base64 `X-PAYMENT` header into its x402 payment envelope.
+ *
+ * Runtime-neutral and edge-safe (no `Buffer`). Shared by the payer-side
+ * {@link X402Flow} and the server-side paywall so both agree on the wire format.
+ *
+ * @throws {@link X402Error} if the header is missing or not valid base64 JSON.
+ */
+declare function parsePaymentHeader(header: string): X402PaymentEnvelope;
+
+/**
+ * Create a runtime-neutral x402 paywall.
+ *
+ * The paywall advertises {@link X402PaymentRequired} when no valid `X-PAYMENT`
+ * header is present, and otherwise decodes the header and forwards the payment
+ * payload to the verifier's `issueGuarantee`. A successful guarantee means the
+ * payment is cryptographically covered → allow the request. On-chain settlement
+ * (the cycle-clearing `claimNetCredit` flow) is intentionally left as an
+ * out-of-band recipient operation.
+ *
+ * @param verifier - `client.rpc`, the SDK `Client`, or any {@link GuaranteeVerifier}.
+ * @param config - Advertised requirements for the protected resource.
+ */
+declare function createPaywall(verifier: PaywallVerifier, config: PaywallConfig): Paywall;
+
+export { type GuaranteeVerifier, PaymentRequirementsExtra, type Paywall, type PaywallConfig, type PaywallDecision, type PaywallGuarantee, type PaywallInput, type PaywallVerifier, type X402PaymentEnvelope, X402PaymentRequired, X402ResourceInfo, base64ToBytes, base64ToUtf8, bytesToBase64, createPaywall, parsePaymentHeader, utf8ToBase64 };

package/dist/server.d.ts

@@ -0,0 +1,119 @@
+import { o as X402PaymentRequired, v as PaymentRequirementsExtra, r as X402ResourceInfo, x as X402PaymentEnvelopeV1, y as X402PaymentEnvelopeV2 } from './models-B15ouNYG.js';
+export { p as PaymentRequirementsV2 } from './models-B15ouNYG.js';
+
+/**
+ * Edge-safe base64 helpers.
+ *
+ * Uses only Web-standard `atob`/`btoa` + `TextEncoder`/`TextDecoder`, which are
+ * available on Node (>=16), Bun, Deno, browsers, and edge/worker runtimes — so
+ * the server paywall path never depends on Node's `Buffer`.
+ */
+declare function base64ToBytes(b64: string): Uint8Array;
+declare function bytesToBase64(bytes: Uint8Array): string;
+declare function base64ToUtf8(b64: string): string;
+declare function utf8ToBase64(text: string): string;
+
+/** Decoded `X-PAYMENT` envelope: either the V1 or V2 wire shape. */
+type X402PaymentEnvelope = X402PaymentEnvelopeV1 | X402PaymentEnvelopeV2;
+/**
+ * Minimal verification surface the paywall needs: issue a payment guarantee for
+ * an already-serialized wire payload. The SDK `Client`'s `rpc` proxy and its
+ * `RpcProxy` both satisfy this structurally, so callers can pass `client.rpc`.
+ */
+interface GuaranteeVerifier {
+    issueGuarantee(payload: unknown): Promise<Record<string, unknown>>;
+}
+/** A bare verifier, or anything exposing one at `.rpc` (e.g. the SDK `Client`). */
+type PaywallVerifier = GuaranteeVerifier | {
+    rpc: GuaranteeVerifier;
+};
+/** What the framework adapter hands the paywall: method, url, and a header reader. */
+interface PaywallInput {
+    method: string;
+    url: string;
+    /** Case-insensitive header lookup, returning `null` when absent. */
+    header: (name: string) => string | null;
+}
+/** Advertised payment requirements + how to describe the protected resource. */
+interface PaywallConfig {
+    /** Recipient address that collateral is claimed against. */
+    payTo: string;
+    /** Asset (token) address, or the zero address for native ETH. */
+    asset: string;
+    /** Network id (shorthand or CAIP-2) advertised to the payer. */
+    network: string;
+    /** Amount required, as an integer string in the asset's base units. */
+    amount: string;
+    /** Endpoint the payer calls to open/resolve a tab (advertised via `extra.tabEndpoint`). */
+    tabEndpoint: string;
+    scheme?: string;
+    x402Version?: number;
+    description?: string;
+    mimeType?: string;
+    maxTimeoutSeconds?: number;
+    /** Extra requirements (e.g. a V2 validation policy); merged over `tabEndpoint`. */
+    extra?: PaymentRequirementsExtra;
+    /** Override the described resource in the 402 body. */
+    resource?: Partial<X402ResourceInfo>;
+    /** Fully override the advertised 402 body. Takes precedence over every field above. */
+    buildRequirements?: (input: PaywallInput) => X402PaymentRequired;
+}
+interface PaywallGuarantee {
+    /** ABI-encoded guarantee claims (hex). */
+    claims: string;
+    /** BLS12-381 G2 signature (hex). */
+    signature: string;
+    /** Raw guarantee record returned by the core RPC. */
+    raw: Record<string, unknown>;
+}
+type PaywallDecision = {
+    ok: true;
+    guarantee: PaywallGuarantee;
+    responseHeaders: Record<string, string>;
+} | {
+    ok: false;
+    status: 402;
+    headers: Record<string, string>;
+    body: X402PaymentRequired;
+};
+interface Paywall {
+    /** Low-level primitive: decide from a headers-in / decision-out request. */
+    protect(input: PaywallInput): Promise<PaywallDecision>;
+    /**
+     * Web-Fetch convenience wrapper. Returns a 402 `Response` when payment is
+     * required/invalid, or `{ ok: true, headers, guarantee }` for the adapter to
+     * merge onto the downstream response (the headers include `X-PAYMENT-RESPONSE`).
+     */
+    handle(request: Request): Promise<Response | {
+        ok: true;
+        headers: Headers;
+        guarantee: PaywallGuarantee;
+    }>;
+}
+
+/**
+ * Decode a base64 `X-PAYMENT` header into its x402 payment envelope.
+ *
+ * Runtime-neutral and edge-safe (no `Buffer`). Shared by the payer-side
+ * {@link X402Flow} and the server-side paywall so both agree on the wire format.
+ *
+ * @throws {@link X402Error} if the header is missing or not valid base64 JSON.
+ */
+declare function parsePaymentHeader(header: string): X402PaymentEnvelope;
+
+/**
+ * Create a runtime-neutral x402 paywall.
+ *
+ * The paywall advertises {@link X402PaymentRequired} when no valid `X-PAYMENT`
+ * header is present, and otherwise decodes the header and forwards the payment
+ * payload to the verifier's `issueGuarantee`. A successful guarantee means the
+ * payment is cryptographically covered → allow the request. On-chain settlement
+ * (the cycle-clearing `claimNetCredit` flow) is intentionally left as an
+ * out-of-band recipient operation.
+ *
+ * @param verifier - `client.rpc`, the SDK `Client`, or any {@link GuaranteeVerifier}.
+ * @param config - Advertised requirements for the protected resource.
+ */
+declare function createPaywall(verifier: PaywallVerifier, config: PaywallConfig): Paywall;
+
+export { type GuaranteeVerifier, PaymentRequirementsExtra, type Paywall, type PaywallConfig, type PaywallDecision, type PaywallGuarantee, type PaywallInput, type PaywallVerifier, type X402PaymentEnvelope, X402PaymentRequired, X402ResourceInfo, base64ToBytes, base64ToUtf8, bytesToBase64, createPaywall, parsePaymentHeader, utf8ToBase64 };

package/dist/server.js

@@ -0,0 +1,165 @@
+// src/server/base64.ts
+function base64ToBytes(b64) {
+  const binary = atob(b64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i += 1) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
+function bytesToBase64(bytes) {
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += 1) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+function base64ToUtf8(b64) {
+  return new TextDecoder().decode(base64ToBytes(b64));
+}
+function utf8ToBase64(text) {
+  return bytesToBase64(new TextEncoder().encode(text));
+}
+
+// src/errors/index.ts
+var FourMicaError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = this.constructor.name;
+  }
+};
+var X402Error = class extends FourMicaError {
+};
+
+// src/server/envelope.ts
+function parsePaymentHeader(header) {
+  if (!header || typeof header !== "string") {
+    throw new X402Error("missing payment header");
+  }
+  try {
+    const decoded = base64ToUtf8(header);
+    return JSON.parse(decoded);
+  } catch (err) {
+    throw new X402Error(`invalid payment header: ${String(err)}`);
+  }
+}
+
+// src/server/paywall.ts
+var X402_VERSION = 1;
+var DEFAULT_SCHEME = "4mica";
+var PAYMENT_HEADER = "x-payment";
+var PAYMENT_RESPONSE_HEADER = "X-PAYMENT-RESPONSE";
+var JSON_HEADERS = {
+  "content-type": "application/json"
+};
+function resolveVerifier(verifier) {
+  if ("issueGuarantee" in verifier && typeof verifier.issueGuarantee === "function") {
+    return verifier;
+  }
+  const withRpc = verifier;
+  if (withRpc.rpc && typeof withRpc.rpc.issueGuarantee === "function") {
+    return withRpc.rpc;
+  }
+  throw new TypeError(
+    "paywall verifier must expose issueGuarantee() or a .rpc that does"
+  );
+}
+function buildResource(input, config) {
+  return {
+    url: config.resource?.url ?? input.url,
+    description: config.resource?.description ?? config.description ?? "",
+    mimeType: config.resource?.mimeType ?? config.mimeType ?? ""
+  };
+}
+function buildRequirements(input, config, error) {
+  if (config.buildRequirements) {
+    const custom = config.buildRequirements(input);
+    return error ? { ...custom, error } : custom;
+  }
+  const accepts = {
+    scheme: config.scheme ?? DEFAULT_SCHEME,
+    network: config.network,
+    asset: config.asset,
+    amount: config.amount,
+    payTo: config.payTo,
+    maxTimeoutSeconds: config.maxTimeoutSeconds,
+    extra: { tabEndpoint: config.tabEndpoint, ...config.extra }
+  };
+  return {
+    x402Version: config.x402Version ?? X402_VERSION,
+    ...error ? { error } : {},
+    resource: buildResource(input, config),
+    accepts: [accepts]
+  };
+}
+function requireResponse(input, config, error) {
+  return {
+    ok: false,
+    status: 402,
+    headers: { ...JSON_HEADERS },
+    body: buildRequirements(input, config, error)
+  };
+}
+function createPaywall(verifier, config) {
+  const guarantor = resolveVerifier(verifier);
+  async function protect(input) {
+    const paymentHeader = input.header(PAYMENT_HEADER);
+    if (!paymentHeader) {
+      return requireResponse(input, config);
+    }
+    let payload;
+    try {
+      payload = parsePaymentHeader(paymentHeader).payload;
+    } catch (err) {
+      return requireResponse(
+        input,
+        config,
+        err instanceof Error ? err.message : String(err)
+      );
+    }
+    try {
+      const raw = await guarantor.issueGuarantee(payload);
+      const claims = typeof raw.claims === "string" ? raw.claims : "";
+      const signature = typeof raw.signature === "string" ? raw.signature : "";
+      const guarantee = { claims, signature, raw };
+      return {
+        ok: true,
+        guarantee,
+        responseHeaders: {
+          [PAYMENT_RESPONSE_HEADER]: utf8ToBase64(
+            JSON.stringify({ success: true, guarantee: { claims, signature } })
+          )
+        }
+      };
+    } catch (err) {
+      return requireResponse(
+        input,
+        config,
+        err instanceof Error ? err.message : String(err)
+      );
+    }
+  }
+  async function handle(request) {
+    const decision = await protect({
+      method: request.method,
+      url: request.url,
+      header: (name) => request.headers.get(name)
+    });
+    if (!decision.ok) {
+      return new Response(JSON.stringify(decision.body), {
+        status: decision.status,
+        headers: decision.headers
+      });
+    }
+    return {
+      ok: true,
+      headers: new Headers(decision.responseHeaders),
+      guarantee: decision.guarantee
+    };
+  }
+  return { protect, handle };
+}
+
+export { base64ToBytes, base64ToUtf8, bytesToBase64, createPaywall, parsePaymentHeader, utf8ToBase64 };
+//# sourceMappingURL=server.js.map
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server/base64.ts","../src/errors/index.ts","../src/server/envelope.ts","../src/server/paywall.ts"],"names":[],"mappings":"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","file":"server.js","sourcesContent":["/**\n * Edge-safe base64 helpers.\n *\n * Uses only Web-standard `atob`/`btoa` + `TextEncoder`/`TextDecoder`, which are\n * available on Node (>=16), Bun, Deno, browsers, and edge/worker runtimes — so\n * the server paywall path never depends on Node's `Buffer`.\n */\n\nexport function base64ToBytes(b64: string): Uint8Array {\n  const binary = atob(b64);\n  const bytes = new Uint8Array(binary.length);\n  for (let i = 0; i < binary.length; i += 1) {\n    bytes[i] = binary.charCodeAt(i);\n  }\n  return bytes;\n}\n\nexport function bytesToBase64(bytes: Uint8Array): string {\n  let binary = \"\";\n  for (let i = 0; i < bytes.length; i += 1) {\n    binary += String.fromCharCode(bytes[i] as number);\n  }\n  return btoa(binary);\n}\n\nexport function base64ToUtf8(b64: string): string {\n  return new TextDecoder().decode(base64ToBytes(b64));\n}\n\nexport function utf8ToBase64(text: string): string {\n  return bytesToBase64(new TextEncoder().encode(text));\n}\n","/** Base class for all 4Mica SDK errors. Sets `error.name` to the subclass name. */\nexport class FourMicaError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = this.constructor.name;\n  }\n}\n\n/** Thrown when the SDK configuration is invalid (e.g. missing required fields or bad URL). */\nexport class ConfigError extends FourMicaError {}\n\n/** Thrown when a 4Mica core RPC call fails. Includes the HTTP status and raw response body. */\nexport class RpcError extends FourMicaError {\n  readonly status?: number;\n  readonly body?: unknown;\n\n  constructor(message: string, options?: { status?: number; body?: unknown }) {\n    super(message);\n    this.status = options?.status;\n    this.body = options?.body;\n  }\n}\n\n/** Thrown when the SDK client fails to initialise (e.g. chain ID mismatch). */\nexport class ClientInitializationError extends FourMicaError {}\n\n/** Thrown when signing a payment claim fails (e.g. unsupported scheme, address mismatch). */\nexport class SigningError extends FourMicaError {}\n\n/** Thrown when an on-chain contract call fails or returns an unexpected result. */\nexport class ContractError extends FourMicaError {}\n\n/** Thrown when BLS certificate verification fails (e.g. domain mismatch, invalid encoding). */\nexport class VerificationError extends FourMicaError {}\n\n/** Thrown when an x402 HTTP payment flow encounters an error. */\nexport class X402Error extends FourMicaError {}\n\n/** Base class for authentication-related errors. */\nexport class AuthError extends FourMicaError {}\n\n/** Thrown when the auth URL is invalid or unreachable. */\nexport class AuthUrlError extends AuthError {}\n\n/** Thrown when a network-level error occurs during authentication. */\nexport class AuthTransportError extends AuthError {}\n\n/** Thrown when the auth server response cannot be decoded. */\nexport class AuthDecodeError extends AuthError {}\n\n/** Thrown when the auth server returns an error response. Includes HTTP status and body. */\nexport class AuthApiError extends AuthError {\n  readonly status?: number;\n  readonly body?: unknown;\n\n  constructor(message: string, options?: { status?: number; body?: unknown }) {\n    super(message);\n    this.status = options?.status;\n    this.body = options?.body;\n  }\n}\n\n/** Thrown when auth configuration is invalid. */\nexport class AuthConfigError extends AuthError {}\n\n/** Thrown when an authenticated operation is attempted without auth being configured. */\nexport class AuthMissingConfigError extends AuthConfigError {}\n","import { X402Error } from \"@/errors\";\nimport { base64ToUtf8 } from \"@/server/base64\";\nimport type { X402PaymentEnvelope } from \"@/server/models\";\n\n/**\n * Decode a base64 `X-PAYMENT` header into its x402 payment envelope.\n *\n * Runtime-neutral and edge-safe (no `Buffer`). Shared by the payer-side\n * {@link X402Flow} and the server-side paywall so both agree on the wire format.\n *\n * @throws {@link X402Error} if the header is missing or not valid base64 JSON.\n */\nexport function parsePaymentHeader(header: string): X402PaymentEnvelope {\n  if (!header || typeof header !== \"string\") {\n    throw new X402Error(\"missing payment header\");\n  }\n  try {\n    const decoded = base64ToUtf8(header);\n    return JSON.parse(decoded) as X402PaymentEnvelope;\n  } catch (err) {\n    throw new X402Error(`invalid payment header: ${String(err)}`);\n  }\n}\n","import { utf8ToBase64 } from \"@/server/base64\";\nimport { parsePaymentHeader } from \"@/server/envelope\";\nimport type {\n  GuaranteeVerifier,\n  Paywall,\n  PaywallConfig,\n  PaywallDecision,\n  PaywallGuarantee,\n  PaywallInput,\n  PaywallVerifier,\n} from \"@/server/models\";\nimport type {\n  PaymentRequirementsV2,\n  X402PaymentRequired,\n  X402ResourceInfo,\n} from \"@/x402/models\";\n\nconst X402_VERSION = 1;\nconst DEFAULT_SCHEME = \"4mica\";\nconst PAYMENT_HEADER = \"x-payment\";\nconst PAYMENT_RESPONSE_HEADER = \"X-PAYMENT-RESPONSE\";\nconst JSON_HEADERS: Record<string, string> = {\n  \"content-type\": \"application/json\",\n};\n\nfunction resolveVerifier(verifier: PaywallVerifier): GuaranteeVerifier {\n  if (\n    \"issueGuarantee\" in verifier &&\n    typeof (verifier as GuaranteeVerifier).issueGuarantee === \"function\"\n  ) {\n    return verifier as GuaranteeVerifier;\n  }\n  const withRpc = verifier as { rpc?: GuaranteeVerifier };\n  if (withRpc.rpc && typeof withRpc.rpc.issueGuarantee === \"function\") {\n    return withRpc.rpc;\n  }\n  throw new TypeError(\n    \"paywall verifier must expose issueGuarantee() or a .rpc that does\",\n  );\n}\n\nfunction buildResource(\n  input: PaywallInput,\n  config: PaywallConfig,\n): X402ResourceInfo {\n  return {\n    url: config.resource?.url ?? input.url,\n    description: config.resource?.description ?? config.description ?? \"\",\n    mimeType: config.resource?.mimeType ?? config.mimeType ?? \"\",\n  };\n}\n\nfunction buildRequirements(\n  input: PaywallInput,\n  config: PaywallConfig,\n  error?: string,\n): X402PaymentRequired {\n  if (config.buildRequirements) {\n    const custom = config.buildRequirements(input);\n    return error ? { ...custom, error } : custom;\n  }\n  const accepts: PaymentRequirementsV2 = {\n    scheme: config.scheme ?? DEFAULT_SCHEME,\n    network: config.network,\n    asset: config.asset,\n    amount: config.amount,\n    payTo: config.payTo,\n    maxTimeoutSeconds: config.maxTimeoutSeconds,\n    extra: { tabEndpoint: config.tabEndpoint, ...config.extra },\n  };\n  return {\n    x402Version: config.x402Version ?? X402_VERSION,\n    ...(error ? { error } : {}),\n    resource: buildResource(input, config),\n    accepts: [accepts],\n  };\n}\n\nfunction requireResponse(\n  input: PaywallInput,\n  config: PaywallConfig,\n  error?: string,\n): Extract<PaywallDecision, { ok: false }> {\n  return {\n    ok: false,\n    status: 402,\n    headers: { ...JSON_HEADERS },\n    body: buildRequirements(input, config, error),\n  };\n}\n\n/**\n * Create a runtime-neutral x402 paywall.\n *\n * The paywall advertises {@link X402PaymentRequired} when no valid `X-PAYMENT`\n * header is present, and otherwise decodes the header and forwards the payment\n * payload to the verifier's `issueGuarantee`. A successful guarantee means the\n * payment is cryptographically covered → allow the request. On-chain settlement\n * (the cycle-clearing `claimNetCredit` flow) is intentionally left as an\n * out-of-band recipient operation.\n *\n * @param verifier - `client.rpc`, the SDK `Client`, or any {@link GuaranteeVerifier}.\n * @param config - Advertised requirements for the protected resource.\n */\nexport function createPaywall(\n  verifier: PaywallVerifier,\n  config: PaywallConfig,\n): Paywall {\n  const guarantor = resolveVerifier(verifier);\n\n  async function protect(input: PaywallInput): Promise<PaywallDecision> {\n    const paymentHeader = input.header(PAYMENT_HEADER);\n    if (!paymentHeader) {\n      return requireResponse(input, config);\n    }\n\n    let payload: unknown;\n    try {\n      payload = parsePaymentHeader(paymentHeader).payload;\n    } catch (err) {\n      return requireResponse(\n        input,\n        config,\n        err instanceof Error ? err.message : String(err),\n      );\n    }\n\n    try {\n      const raw = await guarantor.issueGuarantee(payload);\n      const claims = typeof raw.claims === \"string\" ? raw.claims : \"\";\n      const signature = typeof raw.signature === \"string\" ? raw.signature : \"\";\n      const guarantee: PaywallGuarantee = { claims, signature, raw };\n      return {\n        ok: true,\n        guarantee,\n        responseHeaders: {\n          [PAYMENT_RESPONSE_HEADER]: utf8ToBase64(\n            JSON.stringify({ success: true, guarantee: { claims, signature } }),\n          ),\n        },\n      };\n    } catch (err) {\n      return requireResponse(\n        input,\n        config,\n        err instanceof Error ? err.message : String(err),\n      );\n    }\n  }\n\n  async function handle(request: Request) {\n    const decision = await protect({\n      method: request.method,\n      url: request.url,\n      header: (name) => request.headers.get(name),\n    });\n    if (!decision.ok) {\n      return new Response(JSON.stringify(decision.body), {\n        status: decision.status,\n        headers: decision.headers,\n      });\n    }\n    return {\n      ok: true as const,\n      headers: new Headers(decision.responseHeaders),\n      guarantee: decision.guarantee,\n    };\n  }\n\n  return { protect, handle };\n}\n"]}

package/package.json

@@ -1,28 +1,48 @@
 {
   "name": "@4mica/sdk",
-  "version": "1.2.17",
-  "description": "TypeScript SDK for interacting with the 4Mica payment network",
+  "version": "1.3.1",
+  "description": "Universal, runtime-neutral TypeScript SDK for the 4Mica payment network",
   "license": "MIT",
+  "type": "module",
   "repository": {
     "type": "git",
-    "url": "https://github.com/4mica-Network/ts-sdk-4mica.git"
+    "url": "https://github.com/4mica-Network/homepage.git",
+    "directory": "packages/sdk"
   },
-  "homepage": "https://github.com/4mica-Network/ts-sdk-4mica#readme",
+  "homepage": "https://github.com/4mica-Network/homepage/tree/main/packages/sdk#readme",
   "bugs": {
-    "url": "https://github.com/4mica-Network/ts-sdk-4mica/issues"
+    "url": "https://github.com/4mica-Network/homepage/issues"
   },
-  "main": "dist/src/index.js",
-  "types": "dist/src/index.d.ts",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/src/index.d.ts",
-      "default": "./dist/src/index.js"
-    }
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./server": {
+      "import": {
+        "types": "./dist/server.d.ts",
+        "default": "./dist/server.js"
+      },
+      "require": {
+        "types": "./dist/server.d.cts",
+        "default": "./dist/server.cjs"
+      }
+    },
+    "./package.json": "./package.json"
   },
   "files": [
     "dist"
   ],
-  "sideEffects": false,
   "engines": {
     "node": ">=18"
   },
@@ -33,48 +53,37 @@
     "4mica",
     "payments",
     "payment-network",
+    "x402",
     "blockchain",
     "sdk",
     "typescript",
-    "ethers"
+    "viem"
   ],
-  "scripts": {
-    "clean": "node -e \"require('node:fs').rmSync('dist',{ recursive: true, force: true })\"",
-    "build": "npm run clean && tsc -p tsconfig.build.json",
-    "test": "vitest run",
-    "test:e2e": "vitest run --config vitest.e2e.config.ts",
-    "example:base-sepolia:x402-v2": "node_modules/.bin/tsx examples/base-sepolia-x402-facilitator-e2e.ts",
-    "example:manual:agents": "node_modules/.bin/tsx examples/manual-agents/demo.ts",
-    "example:wachai:v2": "node_modules/.bin/tsx examples/wachai-v2-demo/demo.ts",
-    "example:deposit": "node_modules/.bin/tsx examples/deposit.ts",
-    "example:yield": "node_modules/.bin/tsx examples/yield.ts",
-    "lint": "eslint . --ext .ts",
-    "fmt": "prettier --check \"{src,tests}/**/*.{ts,js,json}\""
-  },
   "dependencies": {
     "@noble/curves": "^2.2.0",
     "@quillai-network/wachai-validation-sdk": "^0.1.0",
-    "viem": "^2.45.1"
+    "viem": "2.x"
   },
   "optionalDependencies": {
     "@coinbase/cdp-sdk": "^1.49.2"
   },
   "devDependencies": {
-    "@4mica/x402": "^1.2.5",
-    "@coinbase/cdp-sdk": "^1.49.2",
-    "@eslint/js": "^9.39.2",
-    "@types/node": "^25.2.0",
-    "@typescript-eslint/eslint-plugin": "^8.54.0",
-    "@typescript-eslint/parser": "^8.54.0",
-    "dotenv-cli": "^11.0.0",
-    "eslint": "^9.39.2",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-react": "^7.37.5",
-    "globals": "^17.3.0",
-    "prettier": "^3.8.1",
-    "tsx": "^4.21.0",
-    "typescript": "^5.3.3",
-    "typescript-eslint": "^8.54.0",
-    "vitest": "^4.0.17"
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@types/node": "^24.10.1",
+    "publint": "^0.3.14",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.0",
+    "vitest": "^4.1.8",
+    "@4mica/tsconfig": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:e2e": "vitest run --config vitest.e2e.config.ts",
+    "check:exports": "attw --pack . --profile node16 && publint --strict"
   }
-}
+}

package/dist/package.json

@@ -1,80 +0,0 @@
-{
-    "name": "@4mica/sdk",
-    "version": "1.2.16",
-    "description": "TypeScript SDK for interacting with the 4Mica payment network",
-    "license": "MIT",
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/4mica-Network/ts-sdk-4mica.git"
-    },
-    "homepage": "https://github.com/4mica-Network/ts-sdk-4mica#readme",
-    "bugs": {
-        "url": "https://github.com/4mica-Network/ts-sdk-4mica/issues"
-    },
-    "main": "dist/src/index.js",
-    "types": "dist/src/index.d.ts",
-    "exports": {
-        ".": {
-            "types": "./dist/src/index.d.ts",
-            "default": "./dist/src/index.js"
-        }
-    },
-    "files": [
-        "dist"
-    ],
-    "sideEffects": false,
-    "engines": {
-        "node": ">=18"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "keywords": [
-        "4mica",
-        "payments",
-        "payment-network",
-        "blockchain",
-        "sdk",
-        "typescript",
-        "ethers"
-    ],
-    "scripts": {
-        "clean": "node -e \"require('node:fs').rmSync('dist',{ recursive: true, force: true })\"",
-        "build": "npm run clean && tsc -p tsconfig.build.json",
-        "test": "vitest run",
-        "test:e2e": "vitest run --config vitest.e2e.config.ts",
-        "example:base-sepolia:x402-v2": "node_modules/.bin/tsx examples/base-sepolia-x402-facilitator-e2e.ts",
-        "example:manual:agents": "node_modules/.bin/tsx examples/manual-agents/demo.ts",
-        "example:wachai:v2": "node_modules/.bin/tsx examples/wachai-v2-demo/demo.ts",
-        "example:deposit": "node_modules/.bin/tsx examples/deposit.ts",
-        "example:yield": "node_modules/.bin/tsx examples/yield.ts",
-        "lint": "eslint . --ext .ts",
-        "fmt": "prettier --check \"{src,tests}/**/*.{ts,js,json}\""
-    },
-    "dependencies": {
-        "@noble/curves": "^2.2.0",
-        "@quillai-network/wachai-validation-sdk": "^0.1.0",
-        "viem": "^2.45.1"
-    },
-    "optionalDependencies": {
-        "@coinbase/cdp-sdk": "^1.49.2"
-    },
-    "devDependencies": {
-        "@4mica/x402": "^1.2.5",
-        "@coinbase/cdp-sdk": "^1.49.2",
-        "@eslint/js": "^9.39.2",
-        "@types/node": "^25.2.0",
-        "@typescript-eslint/eslint-plugin": "^8.54.0",
-        "@typescript-eslint/parser": "^8.54.0",
-        "dotenv-cli": "^11.0.0",
-        "eslint": "^9.39.2",
-        "eslint-config-prettier": "^10.1.8",
-        "eslint-plugin-react": "^7.37.5",
-        "globals": "^17.3.0",
-        "prettier": "^3.8.1",
-        "tsx": "^4.21.0",
-        "typescript": "^5.3.3",
-        "typescript-eslint": "^8.54.0",
-        "vitest": "^4.0.17"
-    }
-}