@solvapay/core 1.0.0-preview.2 → 1.0.0-preview.21

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

@@ -22,6 +22,7 @@ var index_exports = {};
 __export(index_exports, {
   Env: () => Env,
   SolvaPayError: () => SolvaPayError,
+  getSolvaPayConfig: () => getSolvaPayConfig,
   version: () => version
 });
 module.exports = __toCommonJS(index_exports);
@@ -31,15 +32,34 @@ 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";
   }
 };
+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."
+    );
+  }
+  return {
+    apiKey: solvapaySecretKey,
+    apiBaseUrl: solvapayApiBaseUrl
+  };
+}
 var version = "0.1.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Env,
   SolvaPayError,
+  getSolvaPayConfig,
   version
 });

package/dist/index.d.cts

@@ -11,9 +11,69 @@ declare const Env: z.ZodObject<{
     SOLVAPAY_API_BASE_URL?: string | undefined;
 }>;
 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 {
+    apiKey: string;
+    apiBaseUrl?: string;
+}
+/**
+ * Validates and returns SolvaPay configuration from environment variables.
+ *
+ * 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
+ *
+ * @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";
 
-export { Env, SolvaPayError, version };
+export { Env, type SolvaPayConfig, SolvaPayError, getSolvaPayConfig, version };

package/dist/index.d.ts

@@ -11,9 +11,69 @@ declare const Env: z.ZodObject<{
     SOLVAPAY_API_BASE_URL?: string | undefined;
 }>;
 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 {
+    apiKey: string;
+    apiBaseUrl?: string;
+}
+/**
+ * Validates and returns SolvaPay configuration from environment variables.
+ *
+ * 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
+ *
+ * @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";
 
-export { Env, SolvaPayError, version };
+export { Env, type SolvaPayConfig, SolvaPayError, getSolvaPayConfig, version };

package/dist/index.js

@@ -5,14 +5,33 @@ 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";
   }
 };
+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."
+    );
+  }
+  return {
+    apiKey: solvapaySecretKey,
+    apiBaseUrl: solvapayApiBaseUrl
+  };
+}
 var version = "0.1.0";
 export {
   Env,
   SolvaPayError,
+  getSolvaPayConfig,
   version
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solvapay/core",
-  "version": "1.0.0-preview.2",
+  "version": "1.0.0-preview.21",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
@@ -38,6 +38,7 @@
     "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"
   }
 }