@solvapay/core 1.0.0-preview.8 → 1.0.1-preview.1

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SolvaPay Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,15 +1,87 @@
 # @solvapay/core
 
-Shared types, schemas, and errors.
+Shared types, schemas, errors, and utilities used across all SolvaPay SDK packages.
+
+This package is **runtime-agnostic** -- it contains no Node.js or browser globals and has `"sideEffects": false`.
 
 ## Install
+
 ```bash
+npm install @solvapay/core
+# or
+yarn add @solvapay/core
+# or
 pnpm add @solvapay/core
 ```
 
-## Usage
-```ts
-import { SolvaPayError, Env } from '@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:
+
+```typescript
+import type { SolvaPayConfig } from '@solvapay/core'
+
+const config: SolvaPayConfig = {
+  apiKey: 'sk_live_...',
+  apiBaseUrl: 'https://api.solvapay.com', // optional
+}
 ```
 
-More: docs/architecture.md
+### `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.
+
+## When to Use This Package
+
+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.
+
+## More Information
+
+- [Architecture Guide](../../docs/guides/architecture.md) - Package design and boundaries
+- [Server SDK](../server/README.md) - Server-side paywall protection
+- [React SDK](../react/README.md) - Client-side payment components

package/dist/index.cjs

@@ -32,6 +32,11 @@ var Env = import_zod.z.object({
   SOLVAPAY_API_BASE_URL: import_zod.z.string().url().optional()
 });
 var SolvaPayError = class extends Error {
+  /**
+   * Creates a new SolvaPayError instance.
+   *
+   * @param message - Error message
+   */
   constructor(message) {
     super(message);
     this.name = "SolvaPayError";
@@ -41,7 +46,9 @@ function getSolvaPayConfig() {
   const solvapaySecretKey = process.env.SOLVAPAY_SECRET_KEY;
   const solvapayApiBaseUrl = process.env.SOLVAPAY_API_BASE_URL;
   if (!solvapaySecretKey) {
-    throw new SolvaPayError("Server configuration error: SolvaPay secret key not configured. Missing SOLVAPAY_SECRET_KEY environment variable.");
+    throw new SolvaPayError(
+      "Server configuration error: SolvaPay secret key not configured. Missing SOLVAPAY_SECRET_KEY environment variable."
+    );
   }
   return {
     apiKey: solvapaySecretKey,

package/dist/index.d.cts

@@ -3,15 +3,39 @@ import { z } from 'zod';
 declare const Env: z.ZodObject<{
     SOLVAPAY_SECRET_KEY: z.ZodString;
     SOLVAPAY_API_BASE_URL: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    SOLVAPAY_SECRET_KEY: string;
-    SOLVAPAY_API_BASE_URL?: string | undefined;
-}, {
-    SOLVAPAY_SECRET_KEY: string;
-    SOLVAPAY_API_BASE_URL?: string | undefined;
-}>;
+}, z.core.$strip>;
 type Env = z.infer<typeof Env>;
+/**
+ * Base error class for SolvaPay SDK errors.
+ *
+ * All SolvaPay SDK errors extend this class, making it easy to catch
+ * and handle SDK-specific errors separately from other errors.
+ *
+ * @example
+ * ```typescript
+ * import { SolvaPayError } from '@solvapay/core';
+ *
+ * try {
+ *   const config = getSolvaPayConfig();
+ * } catch (error) {
+ *   if (error instanceof SolvaPayError) {
+ *     // Handle SolvaPay-specific error
+ *     console.error('SolvaPay error:', error.message);
+ *   } else {
+ *     // Handle other errors
+ *     throw error;
+ *   }
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ */
 declare class SolvaPayError extends Error {
+    /**
+     * Creates a new SolvaPayError instance.
+     *
+     * @param message - Error message
+     */
     constructor(message: string);
 }
 interface SolvaPayConfig {
@@ -20,10 +44,28 @@ interface SolvaPayConfig {
 }
 /**
  * Validates and returns SolvaPay configuration from environment variables.
- * Throws SolvaPayError if required environment variables are missing.
+ *
+ * Reads `SOLVAPAY_SECRET_KEY` and optional `SOLVAPAY_API_BASE_URL` from
+ * environment variables and returns a validated configuration object.
  *
  * @returns SolvaPayConfig object with apiKey and optional apiBaseUrl
- * @throws SolvaPayError if SOLVAPAY_SECRET_KEY is missing
+ * @throws {SolvaPayError} If SOLVAPAY_SECRET_KEY is missing
+ *
+ * @example
+ * ```typescript
+ * import { getSolvaPayConfig } from '@solvapay/core';
+ *
+ * try {
+ *   const config = getSolvaPayConfig();
+ *   console.log('API Key configured:', config.apiKey);
+ * } catch (error) {
+ *   console.error('Configuration error:', error.message);
+ * }
+ * ```
+ *
+ * @see {@link SolvaPayConfig} for the return type
+ * @see {@link SolvaPayError} for error handling
+ * @since 1.0.0
  */
 declare function getSolvaPayConfig(): SolvaPayConfig;
 declare const version = "0.1.0";

package/dist/index.d.ts

@@ -3,15 +3,39 @@ import { z } from 'zod';
 declare const Env: z.ZodObject<{
     SOLVAPAY_SECRET_KEY: z.ZodString;
     SOLVAPAY_API_BASE_URL: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    SOLVAPAY_SECRET_KEY: string;
-    SOLVAPAY_API_BASE_URL?: string | undefined;
-}, {
-    SOLVAPAY_SECRET_KEY: string;
-    SOLVAPAY_API_BASE_URL?: string | undefined;
-}>;
+}, z.core.$strip>;
 type Env = z.infer<typeof Env>;
+/**
+ * Base error class for SolvaPay SDK errors.
+ *
+ * All SolvaPay SDK errors extend this class, making it easy to catch
+ * and handle SDK-specific errors separately from other errors.
+ *
+ * @example
+ * ```typescript
+ * import { SolvaPayError } from '@solvapay/core';
+ *
+ * try {
+ *   const config = getSolvaPayConfig();
+ * } catch (error) {
+ *   if (error instanceof SolvaPayError) {
+ *     // Handle SolvaPay-specific error
+ *     console.error('SolvaPay error:', error.message);
+ *   } else {
+ *     // Handle other errors
+ *     throw error;
+ *   }
+ * }
+ * ```
+ *
+ * @since 1.0.0
+ */
 declare class SolvaPayError extends Error {
+    /**
+     * Creates a new SolvaPayError instance.
+     *
+     * @param message - Error message
+     */
     constructor(message: string);
 }
 interface SolvaPayConfig {
@@ -20,10 +44,28 @@ interface SolvaPayConfig {
 }
 /**
  * Validates and returns SolvaPay configuration from environment variables.
- * Throws SolvaPayError if required environment variables are missing.
+ *
+ * Reads `SOLVAPAY_SECRET_KEY` and optional `SOLVAPAY_API_BASE_URL` from
+ * environment variables and returns a validated configuration object.
  *
  * @returns SolvaPayConfig object with apiKey and optional apiBaseUrl
- * @throws SolvaPayError if SOLVAPAY_SECRET_KEY is missing
+ * @throws {SolvaPayError} If SOLVAPAY_SECRET_KEY is missing
+ *
+ * @example
+ * ```typescript
+ * import { getSolvaPayConfig } from '@solvapay/core';
+ *
+ * try {
+ *   const config = getSolvaPayConfig();
+ *   console.log('API Key configured:', config.apiKey);
+ * } catch (error) {
+ *   console.error('Configuration error:', error.message);
+ * }
+ * ```
+ *
+ * @see {@link SolvaPayConfig} for the return type
+ * @see {@link SolvaPayError} for error handling
+ * @since 1.0.0
  */
 declare function getSolvaPayConfig(): SolvaPayConfig;
 declare const version = "0.1.0";

package/dist/index.js

@@ -5,6 +5,11 @@ var Env = z.object({
   SOLVAPAY_API_BASE_URL: z.string().url().optional()
 });
 var SolvaPayError = class extends Error {
+  /**
+   * Creates a new SolvaPayError instance.
+   *
+   * @param message - Error message
+   */
   constructor(message) {
     super(message);
     this.name = "SolvaPayError";
@@ -14,7 +19,9 @@ function getSolvaPayConfig() {
   const solvapaySecretKey = process.env.SOLVAPAY_SECRET_KEY;
   const solvapayApiBaseUrl = process.env.SOLVAPAY_API_BASE_URL;
   if (!solvapaySecretKey) {
-    throw new SolvaPayError("Server configuration error: SolvaPay secret key not configured. Missing SOLVAPAY_SECRET_KEY environment variable.");
+    throw new SolvaPayError(
+      "Server configuration error: SolvaPay secret key not configured. Missing SOLVAPAY_SECRET_KEY environment variable."
+    );
   }
   return {
     apiKey: solvapaySecretKey,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solvapay/core",
-  "version": "1.0.0-preview.8",
+  "version": "1.0.1-preview.1",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -26,18 +26,19 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "zod": "^3.23.8"
+    "zod": "^4.3.6"
   },
   "devDependencies": {
-    "tsup": "^8.0.1",
-    "typescript": "^5.5.4",
-    "vitest": "^2.0.5"
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.2"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm,cjs --dts --tsconfig tsconfig.build.json",
     "test": "vitest run || exit 0",
     "test:unit": "vitest run || exit 0",
     "test:watch": "vitest",
-    "lint": "echo 'no lint yet'"
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix"
   }
 }