@solvapay/core 1.0.9 → 1.1.0

package/README.md

@@ -1,87 +1,37 @@
 # @solvapay/core
 
-Shared types, schemas, errors, and utilities used across all SolvaPay SDK packages.
+[![npm version](https://img.shields.io/npm/v/@solvapay/core.svg)](https://www.npmjs.com/package/@solvapay/core)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-This package is **runtime-agnostic** -- it contains no Node.js or browser globals and has `"sideEffects": false`.
+Shared types, schemas, errors, and utilities used across all SolvaPay SDK packages. Runtime-agnostic — no Node.js or browser globals.
+
+**When to use this package:** rarely install directly. It is pulled in automatically by `@solvapay/server`, `@solvapay/react`, and other packages. Install only if you need shared types or `SolvaPayError` without a full SDK surface.
 
 ## Install
 
 ```bash
-npm install @solvapay/core
-# or
-yarn add @solvapay/core
-# or
 pnpm add @solvapay/core
 ```
 
-## Exports
-
-### `SolvaPayError`
-
-Base error class for all SolvaPay SDK errors. Useful for catching SDK-specific errors:
-
-```typescript
-import { SolvaPayError } from '@solvapay/core'
-
-try {
-  const config = getSolvaPayConfig()
-} catch (error) {
-  if (error instanceof SolvaPayError) {
-    console.error('SolvaPay error:', error.message)
-  }
-}
-```
-
-### `SolvaPayConfig`
-
-Configuration interface for the SDK:
+## Key exports
 
 ```typescript
+import { SolvaPayError, getSolvaPayConfig, Env } from '@solvapay/core'
 import type { SolvaPayConfig } from '@solvapay/core'
-
-const config: SolvaPayConfig = {
-  apiKey: 'sk_live_...',
-  apiBaseUrl: 'https://api.solvapay.com', // optional
-}
-```
-
-### `getSolvaPayConfig()`
-
-Validates and returns configuration from environment variables. Reads `SOLVAPAY_SECRET_KEY` and optional `SOLVAPAY_API_BASE_URL`:
-
-```typescript
-import { getSolvaPayConfig } from '@solvapay/core'
-
-const config = getSolvaPayConfig()
-// config.apiKey - from SOLVAPAY_SECRET_KEY
-// config.apiBaseUrl - from SOLVAPAY_API_BASE_URL (optional)
-```
-
-Throws `SolvaPayError` if `SOLVAPAY_SECRET_KEY` is not set.
-
-### `Env`
-
-Zod schema for validating environment variables:
-
-```typescript
-import { Env } from '@solvapay/core'
-
-const result = Env.safeParse(process.env)
-if (!result.success) {
-  console.error('Invalid environment:', result.error)
-}
 ```
 
-### `version`
-
-The current SDK version string.
+- `SolvaPayError` — base error class for SDK errors
+- `SolvaPayConfig` / `getSolvaPayConfig()` — config from `SOLVAPAY_SECRET_KEY` env
+- `Env` — Zod schema for env validation
+- `version` — current SDK version string
 
-## When to Use This Package
+## See also
 
-Most developers don't need to install `@solvapay/core` directly -- it's automatically included as a dependency of `@solvapay/server`, `@solvapay/react`, and other packages. Install it directly only if you need access to the shared types or error classes without pulling in a full SDK package.
+- [`@solvapay/server`](../server) — server-side paywall and API client
+- [`@solvapay/react`](../react) — client-side checkout components
+- [Architecture guide](../../docs/contributing/architecture.md) — package boundaries
 
-## More Information
+## Support
 
-- [Architecture Guide](../../docs/contributing/architecture.md) - Package design and boundaries
-- [Server SDK](../server/README.md) - Server-side paywall protection
-- [React SDK](../react/README.md) - Client-side payment components
+- **Issues**: [GitHub Issues](https://github.com/solvapay/solvapay-sdk/issues)
+- **Docs**: [docs.solvapay.com/sdks/typescript](https://docs.solvapay.com/sdks/typescript/intro)

package/dist/index.cjs

@@ -22,24 +22,81 @@ var index_exports = {};
 __export(index_exports, {
   Env: () => Env,
   SolvaPayError: () => SolvaPayError,
+  creditsToDisplayMinorUnits: () => creditsToDisplayMinorUnits,
   getSolvaPayConfig: () => getSolvaPayConfig,
+  isZeroDecimalCurrency: () => isZeroDecimalCurrency,
+  minorUnitsPerMajor: () => minorUnitsPerMajor,
   version: () => version
 });
 module.exports = __toCommonJS(index_exports);
 var import_zod = require("zod");
+
+// src/credit-display.ts
+var ZERO_DECIMAL = /* @__PURE__ */ new Set([
+  "bif",
+  "clp",
+  "djf",
+  "gnf",
+  "jpy",
+  "kmf",
+  "krw",
+  "mga",
+  "pyg",
+  "rwf",
+  "ugx",
+  "vnd",
+  "vuv",
+  "xaf",
+  "xof",
+  "xpf"
+]);
+function minorUnitsPerMajor(currency) {
+  return ZERO_DECIMAL.has(currency.toLowerCase()) ? 1 : 100;
+}
+function isZeroDecimalCurrency(currency) {
+  return ZERO_DECIMAL.has(currency.toLowerCase());
+}
+function creditsToDisplayMinorUnits(input) {
+  const { credits, creditsPerMinorUnit, displayExchangeRate, displayCurrency } = input;
+  if (!creditsPerMinorUnit || creditsPerMinorUnit <= 0) return null;
+  const usdMajor = credits / creditsPerMinorUnit / 100;
+  return Math.round(
+    usdMajor * (displayExchangeRate || 1) * minorUnitsPerMajor(displayCurrency)
+  );
+}
+
+// src/index.ts
 var Env = import_zod.z.object({
   SOLVAPAY_SECRET_KEY: import_zod.z.string().min(1),
   SOLVAPAY_API_BASE_URL: import_zod.z.string().url().optional()
 });
 var SolvaPayError = class extends Error {
+  /**
+   * HTTP status code associated with the error, when the error
+   * originated from an upstream API response. Optional so existing
+   * `new SolvaPayError(message)` callsites stay valid.
+   */
+  status;
+  /**
+   * Optional short code for programmatic branching (e.g.
+   * `'missing_secret'`, `'merchant_not_found'`). Free-form by design;
+   * callers should not depend on an exhaustive enum.
+   */
+  code;
   /**
    * Creates a new SolvaPayError instance.
    *
    * @param message - Error message
+   * @param init - Optional `{ status, code }` metadata. Both fields
+   *   are preserved on the instance so downstream consumers
+   *   (`handleRouteError`, MCP trace wrappers) can branch on HTTP
+   *   status without parsing the message string.
    */
-  constructor(message) {
+  constructor(message, init = {}) {
     super(message);
     this.name = "SolvaPayError";
+    this.status = init.status;
+    this.code = init.code;
   }
 };
 function getSolvaPayConfig() {
@@ -60,6 +117,9 @@ var version = "0.1.0";
 0 && (module.exports = {
   Env,
   SolvaPayError,
+  creditsToDisplayMinorUnits,
   getSolvaPayConfig,
+  isZeroDecimalCurrency,
+  minorUnitsPerMajor,
   version
 });

package/dist/index.d.cts

@@ -1,5 +1,21 @@
 import { z } from 'zod';
 
+/**
+ * Shared credit → fiat conversion for MCP bootstrap narration and React
+ * balance surfaces. Backend contract: `credits = USD_cents × creditsPerMinorUnit`
+ * (mint scale; `creditsPerMinorUnit` is typically 100), and
+ * `displayExchangeRate` is USD → display currency (e.g. 9.46 for SEK).
+ */
+declare function minorUnitsPerMajor(currency: string): number;
+declare function isZeroDecimalCurrency(currency: string): boolean;
+/** Fiat value of a credit balance, in MINOR units of `displayCurrency`. */
+declare function creditsToDisplayMinorUnits(input: {
+    credits: number;
+    creditsPerMinorUnit: number;
+    displayExchangeRate: number;
+    displayCurrency: string;
+}): number | null;
+
 declare const Env: z.ZodObject<{
     SOLVAPAY_SECRET_KEY: z.ZodString;
     SOLVAPAY_API_BASE_URL: z.ZodOptional<z.ZodString>;
@@ -31,12 +47,31 @@ type Env = z.infer<typeof Env>;
  * @since 1.0.0
  */
 declare class SolvaPayError extends Error {
+    /**
+     * HTTP status code associated with the error, when the error
+     * originated from an upstream API response. Optional so existing
+     * `new SolvaPayError(message)` callsites stay valid.
+     */
+    readonly status?: number;
+    /**
+     * Optional short code for programmatic branching (e.g.
+     * `'missing_secret'`, `'merchant_not_found'`). Free-form by design;
+     * callers should not depend on an exhaustive enum.
+     */
+    readonly code?: string;
     /**
      * Creates a new SolvaPayError instance.
      *
      * @param message - Error message
+     * @param init - Optional `{ status, code }` metadata. Both fields
+     *   are preserved on the instance so downstream consumers
+     *   (`handleRouteError`, MCP trace wrappers) can branch on HTTP
+     *   status without parsing the message string.
      */
-    constructor(message: string);
+    constructor(message: string, init?: {
+        status?: number;
+        code?: string;
+    });
 }
 interface SolvaPayConfig {
     apiKey: string;
@@ -68,6 +103,7 @@ interface SolvaPayConfig {
  * @since 1.0.0
  */
 declare function getSolvaPayConfig(): SolvaPayConfig;
+
 declare const version = "0.1.0";
 
-export { Env, type SolvaPayConfig, SolvaPayError, getSolvaPayConfig, version };
+export { Env, type SolvaPayConfig, SolvaPayError, creditsToDisplayMinorUnits, getSolvaPayConfig, isZeroDecimalCurrency, minorUnitsPerMajor, version };

package/dist/index.d.ts

@@ -1,5 +1,21 @@
 import { z } from 'zod';
 
+/**
+ * Shared credit → fiat conversion for MCP bootstrap narration and React
+ * balance surfaces. Backend contract: `credits = USD_cents × creditsPerMinorUnit`
+ * (mint scale; `creditsPerMinorUnit` is typically 100), and
+ * `displayExchangeRate` is USD → display currency (e.g. 9.46 for SEK).
+ */
+declare function minorUnitsPerMajor(currency: string): number;
+declare function isZeroDecimalCurrency(currency: string): boolean;
+/** Fiat value of a credit balance, in MINOR units of `displayCurrency`. */
+declare function creditsToDisplayMinorUnits(input: {
+    credits: number;
+    creditsPerMinorUnit: number;
+    displayExchangeRate: number;
+    displayCurrency: string;
+}): number | null;
+
 declare const Env: z.ZodObject<{
     SOLVAPAY_SECRET_KEY: z.ZodString;
     SOLVAPAY_API_BASE_URL: z.ZodOptional<z.ZodString>;
@@ -31,12 +47,31 @@ type Env = z.infer<typeof Env>;
  * @since 1.0.0
  */
 declare class SolvaPayError extends Error {
+    /**
+     * HTTP status code associated with the error, when the error
+     * originated from an upstream API response. Optional so existing
+     * `new SolvaPayError(message)` callsites stay valid.
+     */
+    readonly status?: number;
+    /**
+     * Optional short code for programmatic branching (e.g.
+     * `'missing_secret'`, `'merchant_not_found'`). Free-form by design;
+     * callers should not depend on an exhaustive enum.
+     */
+    readonly code?: string;
     /**
      * Creates a new SolvaPayError instance.
      *
      * @param message - Error message
+     * @param init - Optional `{ status, code }` metadata. Both fields
+     *   are preserved on the instance so downstream consumers
+     *   (`handleRouteError`, MCP trace wrappers) can branch on HTTP
+     *   status without parsing the message string.
      */
-    constructor(message: string);
+    constructor(message: string, init?: {
+        status?: number;
+        code?: string;
+    });
 }
 interface SolvaPayConfig {
     apiKey: string;
@@ -68,6 +103,7 @@ interface SolvaPayConfig {
  * @since 1.0.0
  */
 declare function getSolvaPayConfig(): SolvaPayConfig;
+
 declare const version = "0.1.0";
 
-export { Env, type SolvaPayConfig, SolvaPayError, getSolvaPayConfig, version };
+export { Env, type SolvaPayConfig, SolvaPayError, creditsToDisplayMinorUnits, getSolvaPayConfig, isZeroDecimalCurrency, minorUnitsPerMajor, version };

package/dist/index.js

@@ -1,18 +1,72 @@
 // src/index.ts
 import { z } from "zod";
+
+// src/credit-display.ts
+var ZERO_DECIMAL = /* @__PURE__ */ new Set([
+  "bif",
+  "clp",
+  "djf",
+  "gnf",
+  "jpy",
+  "kmf",
+  "krw",
+  "mga",
+  "pyg",
+  "rwf",
+  "ugx",
+  "vnd",
+  "vuv",
+  "xaf",
+  "xof",
+  "xpf"
+]);
+function minorUnitsPerMajor(currency) {
+  return ZERO_DECIMAL.has(currency.toLowerCase()) ? 1 : 100;
+}
+function isZeroDecimalCurrency(currency) {
+  return ZERO_DECIMAL.has(currency.toLowerCase());
+}
+function creditsToDisplayMinorUnits(input) {
+  const { credits, creditsPerMinorUnit, displayExchangeRate, displayCurrency } = input;
+  if (!creditsPerMinorUnit || creditsPerMinorUnit <= 0) return null;
+  const usdMajor = credits / creditsPerMinorUnit / 100;
+  return Math.round(
+    usdMajor * (displayExchangeRate || 1) * minorUnitsPerMajor(displayCurrency)
+  );
+}
+
+// src/index.ts
 var Env = z.object({
   SOLVAPAY_SECRET_KEY: z.string().min(1),
   SOLVAPAY_API_BASE_URL: z.string().url().optional()
 });
 var SolvaPayError = class extends Error {
+  /**
+   * HTTP status code associated with the error, when the error
+   * originated from an upstream API response. Optional so existing
+   * `new SolvaPayError(message)` callsites stay valid.
+   */
+  status;
+  /**
+   * Optional short code for programmatic branching (e.g.
+   * `'missing_secret'`, `'merchant_not_found'`). Free-form by design;
+   * callers should not depend on an exhaustive enum.
+   */
+  code;
   /**
    * Creates a new SolvaPayError instance.
    *
    * @param message - Error message
+   * @param init - Optional `{ status, code }` metadata. Both fields
+   *   are preserved on the instance so downstream consumers
+   *   (`handleRouteError`, MCP trace wrappers) can branch on HTTP
+   *   status without parsing the message string.
    */
-  constructor(message) {
+  constructor(message, init = {}) {
     super(message);
     this.name = "SolvaPayError";
+    this.status = init.status;
+    this.code = init.code;
   }
 };
 function getSolvaPayConfig() {
@@ -32,6 +86,9 @@ var version = "0.1.0";
 export {
   Env,
   SolvaPayError,
+  creditsToDisplayMinorUnits,
   getSolvaPayConfig,
+  isZeroDecimalCurrency,
+  minorUnitsPerMajor,
   version
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solvapay/core",
-  "version": "1.0.9",
+  "version": "1.1.0",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",